PC Media 22

home *** CD-ROM | disk | FTP | other *** search

/ PC Media 22 / PC MEDIA CD22.iso / share / prog / spm220e / star_ref.doc < prev next >

Wrap

Text File | 1995-10-09 | 205.6 KB | 3,833 lines

S E R I A L P O R T S M A N A G E R v 2.20 ------------------------------------------------------ S.T.A.R.COMM Serial Turbo Async. Resident COMMs ------------------------------------------------------ 10/08/95 ══════════════(C)opyRight HETRU 1991-1995═════════════ 13, chemin de la croix St Vincent 94430 CHENNEVIERES SUR MARNE FRANCE tel: (16-1) 45-93-27-38 CompuServe address: 100414,1524 Internet: 100414.1524@Compuserve.com R E F E R E N C E M A N U A L This document exposes to the programmers the different ways to access to the communication functions offered by the STARCOMM driver (that is about the interrupt 14h when loaded as a BIOS T.S.R.; about the interrupt 21h when loaded by the CONFIG.SYS, i.e. as a DEVICE DRIVER; or, finally, about the call by "INT 14h" or "SCL_servs" if the driver is used under its "library" format with SCLIB.OBJ). A description of the C functions and the PASCAL procedures associated to this driver is thereby added. Note that STARCOMM.EXE could be replaced with STARCOM8.EXE in all the present document (STARCOMM manages up to 4 serial ports whereas STARCOM8 can manages up to 8 of them at the same time...). i TABLE OF CONTENTS I- INTERFACING, for the PROGRAMMERS, from the INT 14h: 1- Direct access to the driver: Normalized BIOS functions: Function 00h: BIOS initialization............................ 2 Function 01h: BIOS writing................................... 2 Function 02h: BIOS reading................................... 2 Function 03h: BIOS control signals status.................... 3 Function 04h: BIOS extended initialization (PS/2 type)....... 4 Function 05h: BIOS control on modem register (PS/2 type)..... 5 Initialization functions: Function 06h: Version of STARCOMM............................ 6 Function 07h: Opening/closing/status of a port............... 6 Function 08h: Changing the active port....................... 6 Function 09h: Controlling the physical parameters of a port.. 7 Function 0Ah: Controlling the authorization of ports access and the locking of the comm speed and format... 8 Function 0Bh: Initialization of the communication format..... 9 Function 0Ch: Reading the used comm-format of a port......... 10 Function 0Dh: Asking informations on a port buffers.......... 10 Function 0Eh: Flushing the two buffers of a port............. 10 Function 0Fh: Flushing the receive buffer of a port.......... 10 Function 10h: Flushing the transmit buffer of a port......... 11 Function 11h: Receive and send time-out definitions.......... 11 Function 12h: Status of the substitution process ?........... 11 Function 13h: Setting the substitution process............... 12 Input/output of byte(s) on the line(s) (using buffers): Function 14h: Reading of N bytes (with expectation).......... 13 Function 15h: Writing of N bytes (with expectation).......... 13 Function 16h: 1 byte Reading (without expectation)........... 14 Function 17h: 1 byte Writing (without expectation)........... 14 Function 18h: 1 byte Reading, NOT destructive................ 14 Function 19h: 1 byte Writing in the receive buffer........... 15 Function 1Ah: Writing of a control string.................... 15 Input/output Controls: Function 1Bh: Expecting the transmit buffer to get empty..... 16 Function 1Ch: Status of the receive buffer ?................. 16 Function 1Dh: Status of the transmit buffer ?................ 16 Function 1Eh: Sending a BREAK signal......................... 17 Function 1Fh: Reading the errors numbers and types........... 18 Function 20h: Checking the modem status signals.............. 19 Function 21h: Status of the hardware hand-shaking ?.......... 20 Function 22h: Seting the hardware hand-shaking............... 20 Function 23h: Status of the Xon/Xoff hand-shaking............ 20 Function 24h: Seting the Xon/Xoff hand-shaking............... 21 Special commands to manage the way STARCOMM is working: Function 25h: Reading the crucial section flag............... 22 Function 26h: Installation of a user function................ 22 Function 27h: Deactivation of the user function.............. 23 Function 28h: Installation of an Int 14h error handler....... 23 Function 29h: Deactivation of the error handler.............. 23 Function 2Ah: Setting the STARCOMM locking in memory......... 24 Function 2Bh: Is STARCOMM loaded as a DEVICE DRIVER ?........ 25 Function 2Ch: Seting the port used by the DEVICE DRIVER...... 25 Function 2Dh: Seting the BIOS emulator....................... 26 Function 2Eh: Checking the computer hardware type............ 26 ii 2- Procedures interfacing for TURBO PASCAL and TURBO-C: - Global variables........................................... 27 - Available procedures and functions......................... 29 3- Description of the PASCAL procedures: Check_STARCOMM_Present....................................... 32 Version...................................................... 32 Open_Port and OpenPort_Buff.................................. 32 Close_Port................................................... 32 Port_Opened.................................................. 32 Interdit_Port................................................ 32 Autorise_Port................................................ 32 EtatVerrouilleComm et VerrouilleComm......................... 33 SLOW_Ems..................................................... 33 FAST_Ems..................................................... 33 Send_SLOW.................................................... 33 Get_Ports_Adresses........................................... 33 Infos_Uart................................................... 33 Set_New_Uart................................................. 33 Infos_Buffs.................................................. 33 Init_Port.................................................... 34 Init_status.................................................. 34 Reset_Init_Status............................................ 34 Flush_buffers................................................ 34 Flush_InBuff................................................. 34 Flush_OutBuff................................................ 34 ResetCOM_and_TimMAX.......................................... 34 Change_com_port.............................................. 35 Attend_Buff_ems_vide......................................... 35 CheckBufferIn................................................ 35 CheckBufferOut............................................... 35 ReadSerie.................................................... 35 WriteSerie................................................... 35 ReadCarSerie................................................. 35 WriteCarSerie................................................ 35 Peek_rcp..................................................... 36 Poke_rcp..................................................... 36 WriteCmde.................................................... 36 Status_Trait_Erreurs......................................... 36 Def_Trait_Erreurs............................................ 36 Etat_du_Modem................................................ 36 set_DTR...................................................... 36 clear_DTR.................................................... 36 set_RTS...................................................... 37 clear_RTS.................................................... 37 set_OUT1..................................................... 37 clear_OUT1................................................... 37 Send_break................................................... 37 Errors_Report................................................ 37 Port_Free.................................................... 37 HandShake_Status............................................. 37 HandShake_setup.............................................. 37 XonoffShaking_Status......................................... 37 XonoffShaking_setup.......................................... 38 Set_routine.................................................. 38 Reset_routine................................................ 38 Unset_routine................................................ 38 iii Set_err_routine.............................................. 38 Reset_err_routine............................................ 38 Unset_err_routine............................................ 38 Verrouille................................................... 38 Deverrouille................................................. 38 GetPortName.................................................. 39 GetPortDevice................................................ 39 ResetPortDevice.............................................. 39 EmulBIOS..................................................... 39 SetEmulBIOS.................................................. 39 OrdiType..................................................... 39 SetOrdiType.................................................. 39 4- Description of the C procedures: Check_STARCOMM_Present....................................... 40 Version...................................................... 40 Open_Port et OpenPort_Buff................................... 40 Close_Port................................................... 40 Port_Opened.................................................. 40 Interdit_Port................................................ 40 Autorise_Port................................................ 41 EtatVerrouilleComm et VerrouilleComm......................... 41 SLOW_Ems..................................................... 41 FAST_Ems..................................................... 41 Send_SLOW.................................................... 41 Get_Ports_Adresses........................................... 41 Infos_Uart................................................... 41 Set_New_Uart................................................. 42 Infos_Buffs.................................................. 42 Init_Port.................................................... 42 Init_status.................................................. 42 Reset_Init_Status............................................ 42 Flush_buffers................................................ 42 Flush_InBuff................................................. 42 Flush_OutBuff................................................ 43 ResetCOM_and_TimMAX.......................................... 43 Change_com_port.............................................. 43 Attend_Buff_ems_vide......................................... 43 CheckBufferIn................................................ 43 CheckBufferOut............................................... 43 ReadSerie.................................................... 44 WriteSerie................................................... 44 ReadCarSerie................................................. 44 WriteCarSerie................................................ 44 Peek_rcp..................................................... 44 Poke_rcp..................................................... 44 WriteCmde.................................................... 45 Status_Trait_Erreurs......................................... 45 Def_Trait_Erreurs............................................ 45 Etat_du_Modem................................................ 45 set_DTR...................................................... 45 clear_DTR.................................................... 45 set_RTS...................................................... 45 clear_RTS.................................................... 45 set_OUT1..................................................... 46 clear_OUT1................................................... 46 Send_break................................................... 46 Errors_Report................................................ 46 Port_Free.................................................... 46 iv HandShake_Status............................................. 46 HandShake_setup.............................................. 46 XonoffShaking_Status......................................... 46 XonoffShaking_setup.......................................... 47 Set_routine.................................................. 47 Unset_routine................................................ 47 Set_err_routine.............................................. 47 Unset_err_routine............................................ 47 Verrouille................................................... 47 Deverrouille................................................. 47 GetPortName.................................................. 47 GetPortDevice................................................ 47 ResetPortDevice.............................................. 48 EmulBIOS..................................................... 48 SetEmulBIOS.................................................. 48 OrdiType..................................................... 48 SetOrdiType.................................................. 48 5- STARCOMM.EXE errors codes..................................... 49 v II- INTERFACING, for the PROGRAMMERS, from the DOS INT 21h: 1- Direct access to the DOS DEVICE DRIVER: Function 3Dh: OPEN-DEVICE: opening a DEVICE.................. 50 Function 3Eh: CLOSE-DEVICE: closing a DEVICE................. 50 Function 3Fh: READ: reading of N bytes....................... 51 Function 40h: WRITE: writing of N bytes...................... 52 Function 44h: Check-INPUT: available bytes to read ?......... 52 Function 44h: Check-OUTPUT: available room in transmit ?..... 52 Function 44h: IOCtrl-READ: Reading the comm. parameters...... 52 Function 44h: IOCtrl-WRITE: Definition of the comm. param.... 53 2- Procedures interfacing for TURBO PASCAL and TURBO-C: - Global variables........................................... 54 - Available procedures and functions......................... 54 3- Description of the procedures interfacing to the PASCAL: Open_COMM.................................................... 55 Close_COMM................................................... 55 IOStream_READ................................................ 55 IOStream_WRITE............................................... 56 CheckCOMMIn.................................................. 56 CheckCOMMOut................................................. 56 ReadCOMM..................................................... 56 WriteCOMM.................................................... 56 4- Description of the procedures interfacing to the C: Open_COMM.................................................... 57 Close_COMM................................................... 57 IOStream_READ................................................ 57 IOStream_WRITE............................................... 58 CheckCOMMIn.................................................. 58 CheckCOMMOut................................................. 58 ReadCOMM..................................................... 58 WriteCOMM.................................................... 58 5- DOS errors codes.............................................. 59 III- INTERFACING, for the PROGRAMMERS, to SCLIB.OBJ.................. 60 ANNEX: Management of the differents hand-shakings.................... 61 1 I- INTERFACING, for the PROGRAMMERS, from the INT 14h: ══════════════════════════════════════════════════════ The interrupt service number 14h protects the registers DS, ES, DI, SI, BX, CX, DX, and BP (as well as, of course, CS:IP, SS:SP and the the Flags indicators register, the Carry-Flags (CF) excepted). The only modified registers are those specified in the "Return" paragraph of each function. Note that AX is always altered. In case of an error, the Carry Flag is active and AH gives the code of the reported error. In case of no error, the Carry Flag is unset (CF=0) and AH=0. Note that in case of an error 5 (AH=5 => specified port is reported unknown by STARCOMM), the information of the registers others than AH (in the return part) is without any meaning ! This new services interrupt number 14h is fully re-entrant. 1- Direct access to the driver: ─────────────────────────────── Use "INT 14h" in assembler, reporting yourself to the reference manual being constituted by the present paragraph. The standard functions 0 to 3 of the BIOS interrupt 14h remain availables even though STARCOMM has been successfully installed in memory... For any high level languages, refer to the reference manual provided with your compiler in order to find how to have "direct access" to the CPU registers and how to activate a precise soft-interrupt (the interrupt number 14h in the occurrence....). For the BorLand PASCAL and C languages, use the interfacing procedures provided in the STARINTF.PAS and STARINTF.C files (Cf. following paragraph...). 2 Function 00h: This function of the BIOS interrupt 14h is filtered by our routine, and then redirected to our treatment; this is done to assure a good initialization of the serial ports COM1: to COM8:, thus being included in our installed serial driver. Call: AH = 00h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = byte profile: b1-b0 Word length 00: 5 bits 01: 6 bits 10: 7 bits 11: 8 bits b2 Number of stop-bits 0: 1 stop-bit. 1: 1.5 stop-bit for a 5 data bits, 2 stop-bits in the other cases. b4-b3 Parity 00 or 10: Without parity 01: Odd parity 11: Even parity b7-b6-b5 Speed 000: 110 bit/s ▌ 100: 1200 bit/s 001: 150 bit/s ▌ 101: 2400 bit/s 010: 300 bit/s ▌ 110: 4800 bit/s 011: 600 bit/s ▌ 111: 9600 bit/s Return: AX = Values of the line status register (AH) and of the modem register (AL), in the same order than the BIOS report. (AX=0 if the port is unknown...). Functions 01h to 03h: When the port pointed by DX is acknowledged but not opened,the requested function is redirected to the initials BIOS functions (that may be emulated if this option is active...). Otherwise, the reactions of these 3 functions are the following: Function 01h= Call: AH = 01h AL= <byte to send> DX= <port number> Return: AX = <Status of port> (Cf. Function 03h) This function functionally reacts like the function 15h does. Function 02h= Call: AH = 02h DX= <port number> Return: AL = <byte received> AH= <Status of the line> (Cf. Function 03h) This function FUNCTIONALLY reacts like the function 14h does. 3 Function 03h= Call: AH = 03h DX= <port number> Return: AX = <Status of port> The call to this function (as well as the call to functions 01h and 02h) provokes a resetting to 0 of all the communication errors flags. The status word bits returned in AX have the following meaning: (for a value of 1) AH = <Line status> Bit 0= data to receive are available in the receiving buffer Bit 1= Overrun(s) received Bit 2= Parity error(s) in receipt Bit 3= Error on stop-bit in receipt Bit 4= BREAK received Bit 5= Available room in transmit buffer Bit 6= The transmit buffer is empty Bit 7= Time-out error (in reading or in writing depending on whether AH=1 or 2 to the call !). In this case of error, all the other bits are 0 and don't have any meaning (this including AL). AL = <Modem status> Bit 0 = delta CTS Bit 1 = delta DSR Bit 2 = delta RI Bit 3 = delta DCD For the 0 to 4 bits, the condition to 1 means: "Occurred at least 1 time since the last call to the present function". Bit 4 = CTS signal status Bit 5 = DSR signal status Bit 6 = RI signal status Bit 7 = DCD signal status 4 Function 04h:This function of the BIOS interrupt 14h is filtered by our routine, and then redirected to our treatment; this is done in order to assure a good initialization of the serial ports COM1: to COM8:, that is embedded by the installed serial port driver. Note that this function 04h only exists on the PS/2 models. Call: AH = 04h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = Permanent state of the BREAK signal. 0: Out service (steady value= 0) 1: In service (steady value= 1) CL = Transmission speed. Only b0 to b3. Set b4 to b7 to a null value. (i.e. CL= 0 to 12 for 110 bits/s to 115200 bits/s.). 0000 for 110 bits/s ▌ 1000 for 19200 0001 " 150 " ▌ 1001 for 28800 0010 " 300 " ▌ 1010 for 38400 0011 " 600 " ▌ 1011 for 57600 0100 " 1200 " ▌ 1100 for 115200 0101 " 2400 " ▌ 1101 (=> 9600) 0110 " 4800 " ▌ 1110 " " 0111 " 9600 " ▌ 1111 " " CH = Word length 00: 5 bits 01: 6 bits 10: 7 bits 11: 8 bits BL = Number of stop-bits 0: 1 stop-bit. 1: 1.5 stop-bit for a 5 data bits, 2 stop-bits in the other cases. BH = Parity 000: Without parity 001: Odd parity 010: Even parity 011: Parity work (= odd indicator) 100: Parity rest (= even indicator) Return: AX = Values of the line status signals (AH) and of the modem status (AL), in the same order than the BIOS report. (AX=0 if the port is unknown...). 5 Function 05h: Direct access to the modem control register. This function is usually not available except on PS/2 models. The OUT2 signal is protected by our function for the installed driver hard-interrupt health ! Call: AH = 05h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <Under-function code> 0: Request the modem status signals. 1: Set the signals indicated by BL. BL = byte to place in the modem control register (if AL=1). bit 0: DTR signal. bit 1: RTS signal. bit 2: exit OUT1. bit 3: exit OUT2: It is filtered !... bit 4: Loop-back mode control. Return: AH = Values of the line status signals. AL = Values of the modem status signals. If call with AL=0: BL = Status of the modem control signals. Function 06h: Ask the RAM loaded driver version number. Call: AH = 06h (DX = port number un-usefull !) Return: AH = 0 AL = <Major code> DI = <2 minor codes> These codes are returned in ASCII. Function 07h: Control the specified port activity. Set the modem control signals in agreement with the activity defined for the port. Resets to 0 the errors flags at any efficient port opening, and adapts the state of the DTR, RTS and OUT2 signals to the real port status. Permits to define the transmission mode to activate: slow (under control of the clock interrupt) or fast (under control of the UART chip). Call: AH = 07h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <Under-function code> 0: Port activation. The DTR, RTS and OUT2 signals are set to 1, and the errors flags are set to 0 when the port activa- tion is successfull; uses the driver internal buffers. 1: Disactivate the port, if there is no more byte(s) to send. All the modem signals are set to 0 when the disactivating is effective. 2: Is the port opened ? 3: Initializing the designated port with the transmission mode to the reduced flow. The port remains in its present state (whereas opened or closed). 4: Initializing the designated port with the transmission mode to an elevated flow. The port remains in its present state (whereas opened or closed). 5: Is the slow transmission mode active ? 6 6: Like 0, but in using external buffers; these are to be reserved in CONVENTIONAL MEMORY and in a UNIQUE MEMORY SEGMENT. In this case are: ES:DI indexes the reserved area (bottom), BX receipt buffer size, CX transmit buffer size. Each buffer size = 256 bytes at least. It IS NECESSARY: DI+BX+CX <= 0FFFFh ! 7: Unconditional port closing. Return: AH = <Error code> 0: No error. AL gives the port status, only for the under-function 2): 0: driver inactive, signals to 0; 1: driver active, DTR and OUT2 to 1. Or AL gives the mode of active transmit (only for the under-function 5): 0: fast transmit flow, 1: slow transmit flow. 1: Specified under-function is unknown. 5: Port specified is unknown. 7: Bytes to send are remaining in the port transmit buffer. The port closing is therefore reported ! (This code could only be received following a call with AL=1...). 8: Port re-activation not done: this port is already active ! (This code could only be returned following a call with AL=0 or 6...). 9: Unable to open: no more available buffers (with AL=0) OR buffers not given in the same memory segment, OR one of the 2 buffers is too small (with AL=6) ! 10: Unable to recover the buffers allocated to the port to close. The port is physi- -cally closed, but a buffers pair is then lost for all ulterior using ! (This error is normally impossible except a serious error of your central memory). Function 08h: Activation of a new port (between COM1: and COM8:). All the acknowledged ports are closed, except the one specified to be opened and reactivated (with an INTERNAL driver buffer). Resets the errors flags to 0 when the new port has revealed itself accessible (...and has therefore been opened !). Call: AH = 08h DX = <port number to activate> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Requested port not found (i.e. "marked unknown") on the used computer, and for the present session (Cf. "/G..." option...). 9: Unable to open: NO available buffer. 10: Impossibility of recovering a buffer allocated to a previous open port ! The specified port to activate is not open: function is interrupted. AL = 0 7 Function 09h: Request information on the available hardware and its exploitation, or definition of new hardware parameters (on a specified port). For the definition of new parameters, it is necessary to keep in mind that the treatment is canceled if the specified address reveals itself incorrect (no UART found). In this case, there won't be any modification in the concerned port initialization. On the other hand, once the address has been validated, the remainder of the function will be fully executed. If the indicated IRQ is not admissible (out of 2,3,4,5,7,10,11,12, or 15; Or IRQ2 requested on an AT, or IRQ5 requested on a XT, or an IRQ superior or equal to 10 is requested on an AT commuter type; Or corresponding vectors found rerouted by an application executed after STARCOMM thus making an IRQ conflict), it will be unknown, and the former IRQ will remain in use. Finally, the number of bytes to exploit on a possible FIFO must be included between 2 and 15. If it is greater than 15, it is brought back to 15. If it equals to 1, it is brought back to 2. A value of 0 forbade to exploit a FIFO, even though it is available to the specified address. All STARCOMM port can be defined by this function (even though it is considered unknown following the installation checking, or resulting from the "/G..." option). If the address is correct and if the former/news IRQ are not rerouted by an other post-loaded program, the port becomes existing even though it was definite unknown before, because it henceforth becomes usable (address and interrupt are good and well initialized...). ATTENTION: Modifying an OPEN port is FORBIDDEN ! Call: AH = 09h AL = <under-function code> 0: Information on the used parameters. 1: Definition of new parameters. DX = <port number to manage> (0 to 7 for COM1: to COM8:). For the under-function 1 (AL=1), it is also necessary to inform the following registers: BX = <New address of the UART>, CH = <IRQ associated to this port> Possible values= 2,3,4,5,7,10,11,12,15 Or: 'A' (or 'a') demanding the function to automatically determine the IRQ on which the UART seems to be installed on. !! NEVER USE The AUTOMATIC IRQ RESEARCH !! UNDER WINDOWS OR THE DOS OPERATING !! SYSTEM WILL CRASH !... CL = <FIFO buffer activity>, 0: FIFO utilization not authorized. >1: Authorized if any FIFO is present. CL must give the number of bytes that the driver will have the right to use in this buffer integrated to the UART. Return: AH = <Error code> 0: No error. 1: Requested under-function unknown. 5: The port is unknown. and, only in return of a call with AL=1: 11: The port is opened (the port must be closed to modify its physical parameters). 8 12: The specified address reveals itself incorrect. The following registers don't have any meaning except if AL=0 to the call, AND if AH=0 OR 5 to the return: AL = <UART type> 1: 8250, 16450 or compatible equivalent, 2: 16550 with included FIFO buffer. BX = <UART address>, CH = <IRQ associated to this UART>, CL = <FIFO buffer activity>, 0: FIFO unknown (UART is not a 16550), or FIFO unactivated, Otherwise: FIFO Present, active and used. CL contains the number of bytes that the driver has the right of using in this UART integrated buffer. Function 0Ah: Control the authorization to access the serial ports COM1: to COM8:. This permits the applications to dynamically adjust any IRQ conflict that may occur on particular materials... It also permits to control the affectation of serial port(s) to some other specific drivers. ATTENTION: If the IRQ associated to the port has been diverted, this function refuses to work and returns an error 5 (this is necessary in order to protect the IRQ chaining in the computer) ! If the new IRQ can be used, the associated port is always returned CLOSED by the function. This function also permits to control the locking of the comm speed and format for each accessible serial port. Call: AH = 0Ah AL = <Code of under-function> 0: Forbade the access to the specified port. (close this port, restores its inits, and disactivates its possible 'user_it') 1: Allow the access to the specified port. ATTENTION: The function 09h, under- function 1, can also reset as accessible a port initially forbidden !). 2: No locking on "Speed/Format". 3: Locking only the speed. 4: Locking only the format. 5: Locking speed AND format. 6: Requesting the Speed/Format locking state DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 1: Nb of under-function unknown. 5: The port is unknown: the access to the port is still forbidden (only under- function 1 for this error...). OR: the IRQ associated to the port is diverted; the function could not be executed without danger (this for the number 2 under-function) ! 10: Impossibility to recover the buffer associated to the port to close. The port is closed but its access is still autho- -rized. A buffer is lost (under-funct 0)! AL = <Speed/Format locking status> Only differs from 0 when AL=6 at call time ! Worth from 2 to 5 according the same coding that the one for AL at call time. 9 Function 0Bh: Initialize communication format and speed. What are the receipt and transmit buffers sizes ? !! ATTENTION: Do NOT use 115200 bauds on a slow PC computer as !! the hard-interrupt receive routine is not working fast !! enough on these machines. Besides, it really worth using !! a 16450 (or 16550) UART type to use speeds greater than !! 9600 Bauds ! Call: AH = 0Bh DX = <port number to manage> (0 to 7 for COM1: to COM8:). BH = Bits transmission speed. Only b0 to b3. Set b4 to b7 at 0 values. (i.e. BH= 0 to 12 for 110 bits/ s to 115200 bits/ s.). 0000 for 110 bits/s ▌ 1000 for 19200 0001 " 150 " ▌ 1001 for 28800 0010 " 300 " ▌ 1010 for 38400 0011 " 600 " ▌ 1011 for 57600 0100 " 1200 " ▌ 1100 for 115200 0101 " 2400 " ▌ 1101 (=> 9600) 0110 " 4800 " ▌ 1110 " " 0111 " 9600 " ▌ 1111 " " BL = Number of data-bits, parity and stop-bits. Only b0 to b6. b7 is to be set null. b1-b0 Word length 00: 5 bits 01: 6 bits 10: 7 bits 11: 8 bits b2 Number of stop-bits 0: 1 stop-bit. 1: 1.5 stop-bit for a 5 data bits, 2 stop-bits in the other cases. b5-b3 Parity xx0: Without parity 001: Odd parity 011: Even parity 101: Parity work (= odd indicator) 111: Parity rest (= even indicator) b6 State of the break signal 0: Out service (steady value=0) 1: In service (steady value=1) Return: AH = <Error code> 0: No error. 5: Specified port is unknown. 6: Speed un-valid. Init. achieved to 9600 bit/s by default. AL = 0 BX = <Size of receipt buffer (in bytes)> CX = <Size of transmit buffer (in bytes)> 10 Function 0Ch: Reading the communication format used by the specified port. !! ATTENTION: Assure yourself that a (at least) 3 bytes !! destination string is provided in order to avoid any data !! destruction in memory, or (WORSE!) to avoid the in-coming !! data bytes to be written over executable code. Call: AH = 0Ch DX = <port number to manage> (0 to 7 for COM1: to COM8:). Where: DI= Seg:Off of the 3 bytes string used to store the initialization data. Return: AH = <Error code> 0: No error. 5: Specified port is unknown. If AH=0 only: byte 1: Serial port concerned (recall), byte 2+3: Communication format, in the same coding that the one used by the initialization function #09. byte 2= used speed, byte 3= used structure Function 0Dh: Acquirement of the useful informations concerning the INTERNAL buffers used by STARCOMM: their sizes, the number of available buffers, and the number of buffer already in use. Call: AH = 0Dh Return: AH = 0 BX = <Size (bytes) of the receipt buffers> CX = <Size (bytes) of the transmit buffers> DH = <Nb. of used buffer(s)> DL = <Nb. of still un-used buffer(s)> Function 0Eh: Set the receipt and transmit buffers empty and reset the errors flags to 0. Call: AH = 0Eh DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. Function 0Fh: Initializes the receipt and set its buffer empty. Call: AH = 0Fh DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. 11 Function 10h: Initializes the transmit and set its buffer empty. Call: AH = 10h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. Function 11h: Permits to set the elapse time at which the driver must generate a time-out error (in reading or in writing), following an un-successful input (or output). To the return of this function, the previous limiting time-out values are returned. Note that the port is initialized (format and speed), its buffers are reseted empty and all its errors flags are set to 0 at this function return. Call: AH = 11h DX = <port number to manage> (0 to 7 for COM1: to COM8:). BH = <Reading time-out> This value must be included between 1 and 255 half second(s). The value 0 allows to un-modify the current value used by the driver (useful if you only want to ask the current used values !). BL = <Writing time-out> Same commentaries as above. Return: AH = <Error code> 0: No error. 5: Specified port unknown. BH = <Precedent reading time-out in use> This value, like above, is included between 1 and 255 half of a second. BL = <PRECEDENT writing time-out in use> Same commentaries as above. Function 12h: Ask the driver the substitution mode that is used, and the code of replacement used for the mode Smode1 (see "Function 13h" for more explanations). Also permits to define the activity status of the function to represent the BREAK into the receipt buffers, using the special code that is associated to the Break-interrupt. Call: AH = 12h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: port nominee definite unknown. AL = {Smode0, Smode1, or Smode2} AL worth (Smode? + 100) if Bmode1 is used; It is NOT modified if Bmode0 is used. BL = <Code of erroneous bytes replacement> BL = <Code to represent a BREAK in the buffer> 12 Function 13h: Set the substitution process working status concerning the deficient bytes in receipt. This process is inactive by default. It allows to fix the location of doubtful received bytes (parity or stop bit error) even when stocked in the receipt buffer. Indeed: in case of error(s), the UART first warns the CPU about this error. It then generates a second interrupt (for the SAME byte) demanding the CPU to read that byte as it has been decoded, in spite of the raised error. Then, the receipt process can store this byte in its buffer in forgetting the error that is associated with (Smode0); it can replace it by a special code in common agreement with your wishes (Smode1); or it can voluntarily lose this byte after having incremented the number of lost bytes in receipt (Smode2: the same flag variable is used here than the one that counts the receipt bytes lost due to a FULL receipt buffer...). It is the present function that allows you to fix what treatment mode must be applied by the driver on the receipt errors. This function also permits to command the "BREAK-interrupt substitution process" (i.e. permits to specify if we want to find a special BREAK-code in the receipt buffer for each BREAK that is received, or NOT...). Call: AH = 13h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <mode of working> 0: mode Smode0. 1: mode Smode1. 2: mode Smode2. 100: mode Bmode0. 200: mode Bmode1. There is NO connection between the 2 "substi -tution" functions Smode and Bmode. You can set Smode using a first call, and then set Bmode in a second call without canceling the effect onto Smode... BL = <Code of replacement> It is the code of substitution used in the only modes Smode1 and Bmode1. The code in BL is to be specified if AL=Smode1 or Bmode 1, but useless otherwise. Return: AH = <Error code> 0: No error, 1: Unknown working mode ! 5: Specified port is unknown. AL = <Active working mode> 0: mode Smode0. 1: mode Smode1. 2: mode Smode2. 100 is added to AL if Bmode1 is active (it is unchanged if Bmode0 is active...). 13 Function 14h: Read data from the receipt buffer. If you ask to read more data than received, this function waits for other data to get in before returning to the calling process. (Loop reading until receipt of a break signal, or time-out, or completion of the request...). Call: AH = 14h DX = <port number to manage> (0 to 7 for COM1: to COM8:). CX = Number of expected bytes. Where: DI= Seg:Off of first byte of the string in which to store the <CX> expected bytes. !! ATTENTION: Assure to reserve a sufficient !! space !... Return: AH = <Error code> 0: No error. 2: Request Interrupted by a break interrupt 3: You asked to read NO byte ! ? . . . 4: Time-out occur in reading. 5: Specified port is unknown. CX = Number of bytes effectively read. Function 15h: Write data to send in the transmit buffer. If you ask to write more data than room remaining in the transmit buffer, this function waits to be able to finish its action before returning to the calling process. (Loop writing, up to the (writing) time-out limit !...). Call: AH = 15h DX = <port number to manage> (0 to 7 for COM1: to COM8:). CX = Number of bytes to send. Where: DI= Seg:Off of the string to write. Return: AH = <Error code> 0: No error. 3: You asked to write NO byte ! ? . . . 4: Time-out occur in writing: !! Too much consecutive TIME-OUT can !! result from 2 differents errors: !! - the communication with the device !! is blocked, Or (/and) !! - an other program has interfered !! in local with our driver, !! inhibiting its hard-interrupts, !! or in modifying the !! programming of the UART. !! It is advisable, for this last !! event, to reset the used port. !! It will reactivate the communication !! when the error comes from the !! local computer. 5: Specified port is unknown. CX = Number of bytes effectively written. 14 Function 16h: Reading, without expectation, one byte from the receipt buffer. Finish immediately, without utilization of any time-out, whether the reading could take place or not ! Call: AH = 16h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 3: No byte is available, Or the specified port is closed ! 5: Specified port is unknown. AL = <read byte> if AH=0, AL=0 otherwise. Function 17h: Writing, without expectation, one byte to the transmit buffer. Finish immediately, without utilization of any time-out, whether the writing could take place or not ! Call: AH = 17h AL = <byte to write> DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 3: No more room in the buffer, Or the specified port is closed ! 5: Specified port is unknown. Function 18h: Not destructive reading of one byte from the receipt buffer. Call: AH = 18h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 3: No available byte, Or the specified port is closed ! 5: Specified port is unknown. AL = <read byte> if AH=0, AL=0 otherwise. 15 Function 19h: Writing, without expectation, one byte into the receipt buffer. This function thus permits to simulate the receipt of a byte. It precisely proceed like the receipt hard-interrupt regarding the hand-shaking flow controls (hard of soft), when this/these is/are active(s): transmit of an 'Xoff' when the buffer becomes too full and Xon/Xoff is supposed acknowledged by the remote, management of CTS and DTR following the same criteria, recognition of the Xon and Xoff codes received if the protocol is locally active, and management of the lost receipt bytes flag when necessary. This function therefore also permits to open a simple producer access to the receipt buffer, that simulates (using software only) the plug of a hardware transmission loop test ! Call: AH = 19h AL = <byte to write> DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 3: No more room in the buffer, Or the specified port is closed ! 5: Specified port is unknown. Function 1Ah: Write a string directly to the specified port, without regarding any of the flow management signals,and in momentarily disactivating the sending of the bytes from the buffer of the normal transmit function. A time limit fixed to 3 clock thicks is respected before every byte is sent. DTR is put to FALSE for the length of this transmit, except if BH is FALSE (i.e. 0): BH="Use DTR in order to specify the send of a control string for the modem"... Thus, if you disactivate the control of DTR, it will be necessary to send the prefix of associated command to the used modem ("+" for an HAYES Compatible modem by default...). The main utilite of this function is to permit the access to a modem (or to all other intelligent device) in order to send it some specific commands made of a block. This writing has therefore main priority and loops until it succeed. Call: AH = 1Ah DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = Number of bytes to send. BH = Utilization of DTR to specify the command ? 0 (FALSE): NO 1 (TRUE): YES Where: DI= Seg:Off of first byte of the string of bytes to send. Return: AH = <Error code> 0: No error. 3: No byte given to send !... 5: Specified port is unknown. AL = 0 16 Function 1Bh: Make an expectation loop until the transmit buffer is empty. This expectation won't last more than the number of half seconds specified to the function. The reaction to decide is then to be made by the calling program ! This expectation function finishes immediately if the specified port is found closed to the call of the function. Call: AH = 1Bh AL = <Maxi last of expectation> (in number of half seconds !) DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: Transmit buffer is empty (no error...), 4: Time-out: the length limits of expectation is over whereas the buffer is not empty yet. 5: Specified port is unknown. (immediate return) Function 1Ch: Is the receipt buffer empty ? How many bytes are there to read from this buffer ? Call: AH = 1Ch DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error, 5: Specified port is unknown. AL = 0 if buffer NOT empty, 1 if buffer empty. CX = Number of bytes to read. Function 1Dh: Is the transmit buffer full ? How many bytes are remaining free in this buffer ? Call: AH = 1Dh DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error, 5: Specified port is unknown. AL = 0 if buffer is NOT full, 1 if buffer is full CX = Number of free bytes. 17 Function 1Eh: transmit of a break interrupt signal via the specified serial port (precisely: sets to 1 the break signal during some milli-seconds, then resets its initial value). In receipt, this signal is stored by the driver of SERIAL PORTS MANAGER, but it normally provokes no change of its working. It is to the application program to define the reaction to adopt to such a signal. The only case that make STARCOMM reacts is when it is blocked in expectation of a reading:in this case, the break interrupt will make to appear the reading "time-out" immediately. Note that a transition to 1 of the break signal could be not detected if it was not initially set to 0 ! (See the function 0Bh to this subject). Call: AH = 1Eh DX = <port number to manage> (0 to 7 for COM1: to COM8:). BL = <Last of the signal to generate> This time-length could take all value between 0 and 250 eighteenth of second; this will therefore make to generate signal long of the alone length of the signal commutation if BL=0, and long of 14 seconds if BL=250 ! Return: AH = <Error code> 0: No error. 5: Specified port is unknown. 18 Function 1Fh: Reading the accounting of error(s) by possible type. The call to this function provokes the reset to 0 of all the errors flags. It belongs to the user of deciding how to react in case of a too frequent error type in the same port. !! ATTENTION: Assure yourself that you provide a destination !! string of (at least) 5 bytes in order to avoid overwriting !! any data (or WORSE executable program code !) in memory ! Call: AH = 1Fh DX = <port number to manage> (0 to 7 for COM1: to COM8:). Where: DI= Seg:Off of the 5 bytes string in which to store the errors flags. Return: AH = <Error code> 0: No error (function treatment is Ok: AL reports the transmission errors...) 5: Specified port is unknown. AL = <Answer code> 0: No transmission error until now. 1: At least one intervening error since the last call to the function 7, 0Eh, 11h or 1Fh. Where: DI is the errors report flag... byte 1: Number of lost bytes in receipt by lack of room in the receipt buffer. byte 2: Number of overrun errors. byte 3: Number of parity errors. byte 4: Number of stop bit errors. byte 5: Number of break interrupts received An equal number to 255 indicates that there was at least 255 errors of specified type since the last call. 19 Function 20h: Request modem status signals, input signals (under- function 0) and output signals (under-functions 1 and 2). 0 --> Reading the modem status: Ready ?, Clear_to_send ?, Ringing ?, Porteuse (carriage) ?, recent(s) change(s) ?, Delta on DSR, CTS, RI or/and DCD ? !! ATTENTION: Assure yourself that you provide a destination !! string of (at least) 10 bytes in order to avoid any !! data or (WORSE !) program code overwriting in memory. !! ATTENTION: The indication on the modem status signals !! are certified only on the open ports. Otherwise, the !! hard interrupt doesn't up-dates these modem signals ! 1 and 2 --> Positioning the DTR, RTS and OUT1 signals in accordance to the calling request. Call: AH = 20h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <code of under function> 0: Ask the modem status signals. In this case only: DI= Seg:Off of the 10 bytes string in which to store the modem status flags. 1: Set to 1 the signals indicated by DI (set concerned bits to 1 in order to request its activation). 2: Set to 0 the signals indicated by DI (set concerned bits to 0 in order to request its extinction). For the under-functions 1 and 2, only the bits 0 (for DTR), 1 (for RTS) and 2 (for OUT1) of DI has a meaning. OUT2 could NOT be accessed (Cf the ANNEX explanation...). Return: AH = <Error code> (and AL=0) 0: No error. 1: Under-function unknown. 5: Specified port unknown. In return of the under-function 0 only: byte 1: Concerned serial port (recall). Return 0 to 7 for COM1: to COM8:. byte 2: Modem ready or not (DSR), byte 3: Authorized to send or not (CTS), byte 4: Detected ringing or not (RI), byte 5: Received carriage or not (DCD), byte 6: Existence of modified status since the last call to the function 19h. !! 2xN successive modifications !! achieved by the driver between !! 2 calls to 0Ah (via the interfacing) !! could nullify their effects !! and therefore make some signals !! appearing as invariable. From there !! the interest of the bytes 7 to 10. byte 7: Nb. of change(s) on DSR ? byte 8: Nb. of change(s) on CTS ? byte 9: Nb. of change(s) on RI ? byte 10: Nb. of change(s) on DCD ? For the bytes 2 to 6: 1 means "YES" (TRUE), and 0 indicates "NO" (FALSE value). The bytes 7 to 10 returns the number of change(s) since the last call (values from 0 to 255). 20 Function 21h: Request if a hardware hand-shaking protocol is used (RTS/CTS, DTR/DSR, RI, DCD or OUT1). Indicates the state in which it is, and whether the transmits are authorized or not. Call: AH = 21h DX = <port number to manage> (0 to 7..COM1: COM8:) AL = <code of request> 1..3 or >6: RTS/CTS protocol (by default). 2: DTR/DSR protocol. 4: Recognition of RI signal (=> Local). 5: Recognition of DCD signal (=> Local). 6: Recognition of OUT1 signal (=> Remote). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. AL = <Answer code> 0: Protocol no used. 'L': Protocol managed in <L>ocal mode. 'E': Protocol managed in r<E>mote mode. 'B': Protocol managed in ilateral mode. !! 'L,' 'E' or 'B' to the only choice for !! the RTS/CTS and DTR/DSR protocols.'L' for !! RI and DCD, and 'E' for OUT1=COMPULSORY ! DI = <Value of control flag> (EXCEPT OUT1) 0: FALSE= suspended transmits (or: OUT1). 1: TRUE = possible transmits. Function 22h: Indicate to the driver if it must manage a hardware hand-shaking protocol (RTS/CTS, DTR/DSR, both, RI, DCD or OUT1...). Call: AH = 22h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <code of request> 3: RTS/CTS and DTR/DSR. otherwise: like AL under the function 21h ! BH = <code of command> 0: Disactivate Protocol(s) (by default). 'L': Protocol in <L>ocal mode. 'E': Protocol in r<E>mote mode. 'B': Protocol in ilateral mode. Return: AH = <Error code> 0: No error. 5: Specified port is unknown. Function 23h: Request if the software hand-shaking protocol Xon/Xoff is used and, if it is the case, its working mode. Indicate the state in which it is (authorized transmit or not). Specify the codes used for Xon and Xoff, as well as the present number of Xoff received and not acknowledged by consecutives Xon to their arrival. !! ATTENTION: Assure yourself that you provide an (at least) 5 !! bytes destination string in order to avoid any data or !! (WORSE!) executable code overwriting in memory. Call: AH = 23h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Where: DI= Seg:Off of the 5 bytes string in which to store the Xon/Xoff protocol's values. 21 Return: AH = <Error code> 0: No error. 5: Specified port is unknown. AL = <Answer code> 0: "NO, Xon/Xoff is not used". 1: "YES, Xon/Xoff is used". byte 1: Code used for Xon. byte 2: Code used for Xoff. byte 3: Number of Xoff not acknowledged. Remain to 0 if Xon/Xoff, though active in local or bilateral mode, proves out to be useless due to a good synchronization between the 2 linked computers ! This byte therefore reflects the degree of activity of Xon/Xoff protocol: there is indeed always more communicated Xoff than Xon as this hand-shaking must enter in work. If, by regular test of this byte,your program note a tendency to regular increase, your program is here-by informed that it should send less quickly its data because it probably runs on a greatly faster station that the remote site ! This slowing is not however vital to the safe guard of a good link. Note that this indicator is not reseted to 0 but by the Xon/Xoff hand-shake setup function byte 4: Present status of the flow management flag (...is it Xon or Xoff) ? byte 5: Utilization mode of Xon/Xoff ? 0: Protocol not used. 'L': Protocol managed in <L>ocal. 'E': Protocol managed in r<E>mote. 'B': Protocol managed in ilateral. Function 24h: Indicate to the driver if it must use Xon/Xoff. Definition of the codes to use for Xon and Xoff. Call: AH = 24h DX = <port number to manage> (0 to 7 for COM1: to COM8:). AL = <code of command> 0: "NO, don't use Xon/Xoff !" (by default) 'L': Use it in <L>ocal mode. 'E': Use it in r<E>mote mode. 'B': Use it in ilateral mode. BH = <code for Xon> (11h in standard) BL = <code for Xoff> (13h in standard) Always specify the values of these codes, even though these values are "standards" ! Return: AH = <Error code> 0: No error. 5: Specified port is unknown. 22 Function 25h: Reading of the critical section flag (i.e. "semaphore") associated to the management of the specified port. Note that this flag is essentially interesting for a process activated by a hardware interrupt, the priority of which is more elevated than the one used by the serial port; and this when such a process wants to reach the hardware by itself (the UART in the occurrence...). "Is the specified port set as free ?" Call: AH = 25h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. AL = <Answer code> 0: "NO, Specified port is occupied". 1: "YES, Specified port is free". Function 26h: Indicate the driver a user routine to activate with the hardware interrupt associated to the specified port. !! ATTENTION: Assure yourself on the disactivation of the !! user routine before finishing the application program: as !! its code could be eliminated from the RAM after the end of !! the application, an elevated risk of crash exists otherwise. !! Do take all the using precautions associated to the !! writing of an interrupt in order to develop your routine ! !! It must be referenced as a "PROC FAR", i.e. it must finish !! by a "RETF" assembler instruction. !! This routine will be called by the serial driver hardware !! interrupt bound to the UART, after each of its activation. !! It is protected against the recursives calls by the driver !! itself; therefore you don't have to take care of this !! possible problem. The AX, BX, CX and DX registers are !! preserved before the call to the user routine. Call: AH = 26h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Where: DI=Seg:Off of the routine to activate. (If value is: DI=0000:0000, there won't be installation of any new routine...). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. If AH = 0: AL = <Report> 0: There was no user interrupt before. 1: A user interrupt was already active, and has been replaced by your new "interrupt" If AL = 1 to the return: ES:DI gives the pointer associated to the previous installed user routine... Process-call: To the call of your function, the following information are stored by the AL register: AL = <Last event deserved> It is the reason of the last hardware interrupt activation. The possible values are: 0: Change of the modem status signal(s). 2: Transmit a byte. 4: Correct receipt of a new byte. 6: Error on a received byte. The content of any other register must be considered as unpredictable. 23 Function 27h: Indicate the driver to disactivate the user routine. Call: AH = 27h DX = <port number to manage> (0 to 7 for COM1: to COM8:). Return: AH = <Error code> 0: No error. 5: Specified port is unknown. Function 28h: Indicate the driver a special routine to activate as soon as the STARCOMM interrupt 14h (functions 06h and following...) return an internal working error (i.e. when AH is not NULL to the return). !! ATTENTION: Same general writing instructions that for the !! user interrupt routine. !! This routine is not protected against the re-entrance => !! Do not use any local user variable in order to preserve !! the re-entrance (that must characterize ALL the It. 14h !). Call: AH = 28h Where: DI= Seg:Off of the routine to activate. (If DI= 0000:0000, there won't be any activation of a new routine...). Return: AH = 0 AL = <Report> 0: No previous user routine installed. 1: A routine was already set, and it has just been replaced by the one specified. If AL=1 to the return: ES:DI gives the pointer associated to the previous routine that was installed before. Process-call: To the call of your function, the following information are stored: AH = <Treatment error code> (see the summary in paragraph I-5...). DX = <Port number addressed at the time of the error> (0 to 7 for COM1: to COM8:. It may not have any meaning for a 0, 1 or 13 error: this depends upon the express request that that lastly induced the error !). All other registers must be considered as unpredictable. Function 29h: Indicate the driver to disactivate the error handler. Call: AH = 29h Return: AX = 0 24 Function 2Ah: Control the locking of the driver presence in memory. This function allows to ask and define the lock status: if the locking is active, the installed driver may NOT be removed from the RAM, as long as an un-locking call is not initiated. (This corresponds to the error message "Un-installation locked by an application program !" from the driver). This possibility of STARCOMM must not be exploited but by the communication applications programmers that are back-ground working, or that - for a precise reason - doesn't want to take any risks of seeing the driver to disappear from the memory (after having executed COMMAND.COM as a son process in order to open a DOS window for example !...). This function 2Ah thus permits to bring a means of security in these executions. It is therefore clear that it is necessary not to provide any mean(s) to the operator/standard user of controlling himself the STARCOMM locking from the DOS prompt ! REMARK: If N calls take place in order to provoke a locking, N un-locking calls will be necessary in order to effectively get the driver un-locked. This permits the pacific coexistence between several programs that all use the 2Ah locking function! Rem: Useless under SCLIB, this function is there unknown (in return, AH=1 is then systematic). Call: AH = 2Ah AL = <Code of under function> 0: Locking status ? (BL then un-useful). 1: Set the locking as indicated by BL. BL = <Locking status requested> 0: FALSE=> Disactivate the locking. 1: TRUE=> Activate the locking. (DX = port number not compulsory !) Return: AH = <Error code> 0: No error. 1: under-function number unknown, or requested locking status is unknown (i.e. not compliant, i.e. <>0 and<>1 !) AL = <Locking status> Only meaningful if AL=0 to the call and if there is no error reported via the AH register to the function return. 0: FALSE=> No locking in progress. otherwise=> active locking, with a locking imbrication equal to the number returned by BL (1 up to 255 !). 25 Function 2Bh: Return the 8 characters string making the name of the DEVICE DRIVER associated to STARCOMM when it is loaded from the CONFIG.SYS. Call: AH = 2Bh Where: DI= Seg:Off of the first byte of the string where to store the 8 expected bytes. !! ATTENTION: Assure to reserve a sufficient !! receiving space (i.e. at least 8 bytes) ! Return: AH = <Error code> 0: No error 13: Driver is NOT loaded as a DEVICE DRIVER ! Function 2Ch: Request (OR order) to the driver the physical serial port number that is to be accessed by the logical DEVICE DRIVER port. This function remains without any effect if STARCOMM.EXE was not loaded from CONFIG.SYS (that is: as a DEVICE DRIVER...) ! Call: AH = 2Ch DX = <port number to manage>, if AL=1 only. (0 to 7 for COM1: to COM8:). AL = <Code of under function> 0: What physical port is in use ? 1: Set the logical port on the physical port specified by DX. Return: AH = <Error code> 0: No error 1: Under-function number unknown. 5: Specified port is unknown ! (Commutation o.k. if the port is included between 0 and 8, unknown otherwise). 13: driver NOT loaded as a DEVICE DRIVER ! If AL=0 to the call (under-function 0), and excepted in case of an error (we get AH=0 to the return): AL = <Physical serial port number used> (0 to 7 for COM1: to COM8:). 26 Function 2Dh: Control the working authorization of the serial commu- -nication BIOS emulator. Call: AH = 2Dh AL = <Code of under function> 0: Activity of the BIOS emulator ? 1: Set the BIOS emulator activity. BL = <Activation command code> BL doesn't have any sense if AL=1 to the call. 0: Stopping the BIOS emulator. 1: Activating the BIOS emulator. Return: AH = <Error code> 0: No error 1: Under-function number unknown. AL = <Working of the emulator> AL is 0 if AL=1 to the call. 0: BIOS emulator inactive. 1: BIOS emulator active. Function 2Eh: Control of the computer architectural type flag. The interest concerns the access to the IRQ that is function of the computer type. Note that this recognition is normally fully automatic ! All arbitrary modification must not be made excepted in ACQUAINTANCE of a reason !... Call: AH = 2Eh AL = <Under-function code> 0: Recognized type for the computer ? 1: Force the definition of the type. BL = <Type code> BL does have sense only when AL=1 to the call: 1: PC Type 2: XT Type 3: AT Type Return: AH = <Error code> 0: No error 1: Under-function number unknown. AL = <Computer type currently acknowledged> AL is 0 if AL=1 to the call. 1: PC, 2: XT, 3: AT, 4: PS/2-non AT, 5: PS/2-AT 27 2- Definition of the procedures interfacing to the PASCAL and to the C: ─────────────────────────────────────────────────────────────────────── With the C or PASCAL languages, use the procedures provided in the STARINTF files (.C or .PAS) in order to reach to the serial port(s) in using SERIAL PORTS MANAGER's STARCOMM driver. For the Turbo-Pascal(C) language, TESTSTAR.PAS is to your disposal as a demonstration program. For the C language, you could study TERMINAL.C. ────────────────────- Global variables: ────────────────────- RS_accessible: Boolean (byte in C) indicating whether the driver was found in memory (TRUE/1) or not (FALSE/0), this to the level of the interrupt 14h interfacing. BasePort1 to BasePort4: Addresses of the first UART registers associated to each serial port from COM1: to COM4:. The values kept in these variables are the standards addresses by default (COM1:03F8h, COM2:02F8h, COM3:03E8h, and COM4:02E8h...). They are up-dated according to the addresses memorized by the BIOS (situated in 40:00 to 40:08 hexa.) when the "Get_ports_Adresses" procedure is called. Remember that the driver of SERIAL PORTS MANAGER sets this last memory zone in conformity with the addresses that it uses for the serial ports. Therefore the call to "Get_Ports_Adresses" allows to assure of the consistency between your application and the serial driver. When a serial port number I doesn't physically exists, the value of "BasePortI" is 0. RTS_CTS, DTR_DSR, BothCmde, RI, DCD, and OUT1: Possible values for the parameter "Proto_type" of the functions "HandShake_Status" and "HandShake_Setup" that controls the activity of the hardware hand-shaking. Inactive, Local, Eloigne (=remote), Bilateral: Different working modes recognized by the hand-shaking protocols. Correspond to the code L, E, and B of the '/LC', '/EC', ... options. Xon, Xoff: Two bytes giving the codes to use in order to apply the Xon/Xoff protocol. These codes have the respective following values by default: 11h and 13h. It is the functions "XonoffShaking_Status" and "Xonoff Shaking_setup" that uses these constants/variables. Changing the values of these 2 constants, could alter the software hand-shaking exploited: in order to establish an ACK/ETX hand-shaking for example, initializes Xon to 06h and Xoff to 03h... NonActif, Replaces, RempNULL: Possibles working modes for the substitution process of the deficient bytes in receipt. Report to the "Function 13h" higher for more precision on this process. These values are used by the functions "Status_Trait_Erreurs" and "Def_Trait_Erreurs". NoBreakBuff, BreakOnBuff: Possibles working modes for the Break substitution process used to represent,in the receipt buffer,the BREAK received. Type_PC, Type_XT, Type_AT, PS2_PC, PS2_AT: Possible types of known computer architectures. 28 For the PASCAL, a variable indicates the type of the present driver in RAM memory: type_driver: byte that permits to know what driver is loaded in memory: 0=No driver, 1=STARCOMM is BIOS present, 2= STARCOMM is loaded as a DEVICE DRIVER. This variable is automatically up-dated by the STARINTF.PAS library that calls "Check_STARCOMM_Present" since its very first utilization. An another variable permits the calling program to specify to which serial port it addresses its commands: this variable therefore has to be initialized BEFORE any comm. function call (value between 0 and 7 for COM1: to COM8:): CommPort: port concerned by the called function. A boolean array allows to mark the acknowledged and supported driver ports (values up-dated when the "COMM_Opened" function is called !): ComExist[0..7] ... (ComExist[0]= TRUE if COM1: exist, etc...) In C, some other variables are to be considered as globals in order to gain access to all the possibly needed informations: Format : Current communication format. Pret : Status of "Modem Ready" signal (i.e. DTR) Clear_to_send : Status of CTS signal. Sonnerie : Status of RI signal. Porteuse : Status of DCD signal. dDSR : Change(s) of the DSR status since the last call. dCTS : Change(s) of the CTS status... dRI : Change(s) of the RI status... dDCD : Change(s) of the DCD status... Buff_overflow : Number of lost bytes in receipt by lack of room in the receipt buffer. Engorgement : Number of overrun errors. Parity : Number of parity errors. Stop_bit : Number of stop-bit errors. Break_it : Number of intervening 'break-interrupt' in receipt. CommPort and ComExist[0..7] are also defined for the C language. "type_driver" is not, on the other hand, defined (it is necessary to call oneself "Check_STARCOMM_Present" in C !). 29 ──────────────────────────────────- Available procedures/functions: ──────────────────────────────────- Check_STARCOMM_Present: Indicates if the SERIAL PORTS MANAGER driver is present in memory.If the case occurs, up-dates the global variables of the interfacing to the advance language. CALL THIS function in order to initialize the driver use (excepted in PASCAL for which this call is automatic thanks to the ".TPU" UNIT file structure...). Version: Returns the ASCII number of the loaded driver version. Open_Port and OpenPort_Buff: Provokes the opening of the serial port specified by the "CommPort" variable and sets to 1 the DTR and OUT2 modem control signals. Resets to 0 the errors flags concerning the link when there are no indicated errors in return. "Open_Port" provokes the utilization of one of the internal buffers pairs available to the driver, whereas "OpenPort_Buff" allows to associate external memory buffers to a port (this offering a more flexible exploitation !). Close_Port: Provokes the closing of the port specified by "CommPort", and the reset to 0 of the modem control signals (when the closing is possible !). Port_Opened: Returns TRUE (value 1 in C) if the designated port is opened, and FALSE (0 in C) if the port is closed. Interdit_Port: Permits to forbid the access to the "CommPort" serial port. Its initializations are restored and the port is closed before its access gets forbidden. Autorise_Port: Permits to allow the access to the "CommPort" port if we detect it points to a usable UART. Otherwise the port remains forbidden ! EtatVerrouilleComm et VerrouilleComm: Controls the locking of the speeds and formats of the serial ports. SLOW_Ems: Initializes the slow transmit on the designated "CommPort" port, without modifying the activity status of this port. FAST_Ems: Initializes the fast transmit on the designated "CommPort" port, without modifying the activity status of this port. Send_SLOW: Information on the transmission mode in progress on the "CommPort" port. Get_Ports_Adresses: Get the UART basis addresses in the BIOS "mail box" (Ports 0 to 3). Infos_Uart: Permits to know, for every port, the type of used UART, its address, the hard interrupt associated to it and, if it has a FIFO buffer, the use made of this internal buffer. Set_New_Uart: Permits the address, the IRQ and the authorized exploitation of a FIFO to be reseted for one port of STARCOMM. New parameters are not acknow- -ledged if no UART is found to the specified address. An un-supported IRQ is not acknowledged too (without return of an error code in this last case...). Infos_Buffs: Informations on the sizes and the use status of the serial communication driver internals buffers. Init_Port: Resets the specified communication port and resets to 0 the comm. errors flags (Cf. Change_com_port below...). Informations on the transmission buffers sizes. Init_status: Returns the initialization format of the "CommPort" port. 30 Reset_Init_Status: Reactivates the format indicated on the "CommPort" port. Flush_buffers: Emptiness the 2 communication buffers (input And output) and resets to 0 the transmit errors flags. Flush_InBuff: Resets the receipt port, and empties the receipt buffer. Flush_OutBuff: Resets the transmit port, and empties the transmit buffer. ResetCOM_and_TimMAX: Resets the complete communication link, and allows to specify the driver the maximum time-out limits for the reading and writing process. The values of time-out used before the possible change are returned to the calling program. Change_com_port: Changes the used serial port (0 to 7 = COM1: to COM8:), if the specified port is acceptable. Resets to 0 the communication errors flags if the new port is really active. In this case, all the ports are disactivated EXCEPT the one specified. Attend_Buff_ems_vide: Loop until the specified port's transmit buffer gets empty or until the time-out occurs (provided that the port is opened !). CheckBufferIn: Is there any byte to read from receipt buffer ? CheckBufferOut: Could we place some bytes to send in the transmit buffer ? ReadSerie: Read N byte(s) from the receipt buffer. WriteSerie: Transmit N byte(s) to the port, using its transmit buffer. ReadCarSerie: Read a byte from the receipt buffer, without any expectation. WriteCarSerie: Write a byte to the transmit buffer, without any expectation. Peek_rcp: Read the next available byte (if it exists !) from the receipt buffer, without making it to disappear from the buffer. Poke_rcp: Write a byte to the next available entrance of the receipt buffer (this simulates a receipt of this character). ATTENTION: the hand-shaking is managed by this function if it is active: "Poke_rcp" fully simulates the work of the receipt hard interrupt !... WriteCmde: Directly send a N byte(s) string to the serial port used, in momentarily interrupting the standard buffered transmission, this in order not to destroy the string. The flow management codes are not considered by this specific sending process. Utilite: Sending some specific commands to your MODEM (and in fact to all type of particular device attached to your serial port, and able to interpret any particular protocol...). Status_Trait_Erreurs: Request the present substitution process working status. 31 Def_Trait_Erreurs: Management of the substitution process for the erroneous received bytes. Etat_du_Modem: Return the modem status signals associated with the active serial port. set_DTR, clear_DTR, set_RTS, clear_RTS, set_OUT1 and clear_OUT1: Set (or clear) the modem control signal ('set'= 'set to 1' and 'clear'= 'set to 0'...). Send_break: Send a break interrupt via the used serial port. Errors_Report: Was there any bytes transmission errors since the last call to the "Errors_Report" function ? If yes: Nature and number of these errors (for every type of them) ? Port_Free: Can we read or write to the port managed by the driver, without inter- fearing with its work ? (i.e. Is the driver hardware interrupt in progress on the specified port ?). HandShake_Status: Are RTS/CTS or DTR/DSR used ? In what working mode ? Are the transmits currently allowed ? Idem for RI, DCD and OUT1. HandShake_setup: Defined the activity status of RTS/CTS, DTR/DSR, RI, DCD, OUT1 as indicated. XonoffShaking_Status: Is Xon/Xoff used ? Are the transmits currently allowed ? What mode of working is active ? What are the values used in order to code Xon and Xoff ? Number of received Xoff without ulterior discharge by some Xon ? XonoffShaking_setup: Set the Xon/Xoff activity status as indicated. Set_routine (and Reset_routine in PASCAL): Install and activate a user routine to call at the time of each serial port hardware interrupt (but the transmits when the slow transmission mode is used...). Unset_routine: Disactivate the user routine. Set_err_routine (and Reset_err_routine in PASCAL): Install and activate a routine to manage the Interrupt 14h errors. To be created without any variable and without call(s) to the Int. 21h in order to protect the general re-entrance of the interrupt 14h ! Unset_err_routine: Disactivate the interrupt 14h errors management routine. Lock: Driver un-installation is forbidden. Unlock: Driver un-installation is authorized. GetPortName: Permits to know the name used by STARCOMM when it is used as a DEVICE DRIVER (this name may be defined as needed: cf. the "/ND=[xxxxxxxx]" option explained in the chapter III). GetPortDevice: Get the number of the physical serial ports interfaced by the file "COMM:". (Answer without any meaning if STARCOMM.EXE was installed in BIOS mode !) ResetPortDevice: Request to the "COMM:" file to work with the physical serial port specified by the "CommPort" variable. (Remains without effect if STARCOMM.EXE works in BIOS mode !) EmulBIOS (/SetEmulBIOS): Request(/define) the BIOS emulator activity status. OrdiType (/SetOrdiType): Request(/define) the used computer type (PC, XT, PS/2 or AT...). 32 3- Description of the procedures interfacing to the PASCAL: ─────────────────────────────────────────────────────────── Prototype: PROCEDURE|FUNCTION <name>[(<ARGUMENT(S)>)][:<type>]; ---------- Call: - Global call variables - Call parameters Return: - Global return variable - Return parameters - Functions return codes FUNCTION Check_STARCOMM_Present: BYTE; Call: <Nothing> Return: "RS_accessible" to TRUE if a driver is present. 0= no driver, 1= STARCOMM loaded in BIOS mode, 2= STARCOMM loaded as a DEVICE DRIVER. PROCEDURE Version(VAR NumVer: Chn4bytes); Call: <Nothing> Return: "NumVer" contains the driver version in ASCII. FUNCTION Open_Port: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 0 if the port could be opened. 5 if the port is unknown. 8 if the port was already open. 9 if the port doesn't dispose of buffers. FUNCTION OpenPort_Buff(Segment, Offsets, Taille_in, Taille_out: WORD): BYTE; Call: idem preceding+ Seg:Ofs of the buffers and their sizes! Return: idem preceding except 9= "overflowed segment !" FUNCTION Close_Port(ProtegeBuff: BOOLEAN): BYTE; Call: "CommPort" designates the concerned port (0 to 7). "ProtegeBuff" to TRUE if the buffer of transmit must be emptiness before closing the port, to FALSE otherwise. Return: 0 if the port could be closed. 5 if the port is unknown. 7 if it still remains bytes to send (in this case, the port is still opened), if "ProtegeBuff" to TRUE. 10 if it is impossible to recover the associated buffer. FUNCTION Port_Opened: BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: TRUE if the port is opened, FALSE otherwise. FUNCTION Interdit_Port: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 0 if the port could be correctly closed. 10 if the "CommPort" buffers pair is lost. The access to the port is forbidden in both cases. FUNCTION Autorise_Port: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 0 if the access to the port could be authorized. 5 if the port doesn't designate a usable UART (the access to the port then remains forbidden). 33 FUNCTION EtatVerrouilleComm(VAR Mode: BYTE): BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 0 if the port is known. 5 if the port is not known. "Mode" worth 2 to 5 upon the locking status in use (see next function for precise decoding of this...). FUNCTION VerrouilleComm(Mode: BYTE): BYTE; Call: "CommPort" designates the concerned port (0 to 7). "Mode" worth 2 to authorise any change, 3 to lock the speed, 4 to lock the format or 5 to lock both. Return: 0 if the port is known and the work done. 5 if the port is not known. FUNCTION SLOW_Ems: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 5 if the port is unknown. FUNCTION FAST_Ems: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 5 if the port is unknown. FUNCTION Send_SLOW: BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: Return TRUE if the designated port is in slow transmis- -sion mode,FALSE if it works in fast transmission mode. PROCEDURE Get_Ports_Adresses; Call: <Nothing> Return: "BasePort1" to "BasePort4" are up-dated. FUNCTION Infos_Uart(VAR Uart_type: BYTE; VAR Uart_adresse: WORD; VAR Irq, FIFO_actif, Taille_FIFO: BYTE): BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: 0 or 5: the parameters are informed (5 if the port is considered as unknown). FUNCTION Set_New_Uart(Uart_adresse: WORD; Irq, FIFO_actif, Taille_FIFO: BYTE): BYTE; Call: "CommPort" designates the concerned port (0 to 7). "Uart_adresse" <- value of the new address, "Irq" <- value 2,3,4,5,7,10,11,12 or 15 "FIFO_actif" <- 0=NO, 1=YES "Taille_FIFO" <- from 2 to 15 bytes Return: 0 achieved modifications, 5 if the port is unknown, 11 if the port is opened (the port must be closed for modifying its physical parameters), 12 if the address reveals itself incorrect. PROCEDURE Infos_Buffs(VAR Nb_utils, Nb_maxi: BYTE; VAR Taille_InBuff: WORD; VAR Taille_OutBuff: WORD); Call: <Nothing> Return: The parameters are informed. 34 FUNCTION Init_Port(length, stop_bit, parity: CHAR; speed: LONGINT; VAR Taille_InBuff: WORD; VAR Taille_OutBuff: WORD): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "length" = '5,' '6,' '7,' or '8' bits, "stop_bit" = '1' or '2,' "parity" = 'N','P','I','T' or 'R' for <N>o parity, even, Odd,<T> mark, or <R> unmark, speed={110,150,300,600,1200,2400,4800,9600,19200, 28800,38400,57600,115200} bits/second. Return: "Taille_InBuff"= Size of receipt buffer. "Taille_OutBuff"= Size of transmit buffer. (These 2 numbers must gives the bytes number). 1 if incorrect parameters (error=TRUE), 0 (FALSE) otherwise. PROCEDURE Init_status(VAR Format: WORD); Call: "CommPort" designates the concerned port (0 to 7). Return: "Format" variable is up-dated. FUNCTION Reset_Init_status(Format: WORD): BYTE; Call: "CommPort" designates the concerned port (0 to 7). "Format" specifies the reset value to use. Return: 0 (OK!) or 2 (no driver). 5 if the port is unknown. PROCEDURE Flush_buffers; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE Flush_InBuff; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE Flush_OutBuff; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE ResetCOM_and_TimMAX(RdTim_MAX: BYTE; VAR Old_RdTim_MAX:BYTE; WrTim_MAX: BYTE; VAR Old_WrTim_MAX: BYTE); Call: "CommPort" designates the concerned port (0 to 7); "RdTim_MAX" and "WrTim_MAX" must be included between the ASCII values '0' and '9' in order to define a maxi. treatment expectation (in reading or writing) included between ½ and 9 seconds. After the maximum time limit thus defined, the reading or writing procedure will abort, indicating a "TIME-OUT" error. (The concerned procedures are "ReadSerie" and "WriteSerie"). Return: Up-dating of the variable indicated as parameters. "Old_RdTim_MAX" and "Old_WrTim_MAX" returns the values used before the possible induced change by this call to the procedure. Note that a value of 0 placed in "RdTim_MAX" and/or "WrTim_MAX" to the call of the PROCEDURE will make that there won't be modification of the current values for the time-out values used by the driver. The in return variables "Old_RdTim_MAX" and "Old_WrTim_MAX" will however correctly be informed. 35 FUNCTION Change_com_port(port: BYTE): BYTE; Call: "port"= N° of only port to keep opened (0 to 7 for COM1: to COM8:). "CommPort" is up-dated in return. Return: FALSE if the port was not opened yet, TRUE in the other case. FUNCTION Attend_Buff_ems_vide(Temps_maxi: BYTE): BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7), "Temps_maxi": 0 to 255 half a second expectation, to the pleased (that is: maxi. admissible waiting time !). Return: TRUE if the transmit buffer is (finally) emptiness, FALSE if the maximum expectation is reached. FUNCTION CheckBufferIn(VAR nb_a_lire: WORD): BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: "Nb_a_lire"= Nb. of byte(s) present(s) in receipt. FALSE: the BuffIn is emptiness; TRUE otherwise. FUNCTION CheckBufferOut(VAR place_libre: WORD): BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: "place_libre"= Nb. of free byte(s) in the output buff. TRUE: BuffOut has room; FALSE otherwise. FUNCTION ReadSerie(VAR c: CHAR; number: WORD; VAR Nb_received: WORD): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "c"= First byte in order to store the 'string' to receive, "number"= Nb. of byte(s) to read. Return: "Nb_received"= Nb. of byte(s) really read. 0 if the reading of byte(s) appeared correct 2 if the receipt is incorrect (Time-out). 5 if the port is unknown. FUNCTION WriteSerie(VAR c: CHAR; number: WORD; VAR Nb_written: WORD): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "c"= First byte of the 'string' to send, "number"= Nb. of byte(s) making the 'string'. Return: "Nb_written"= Nb. of byte(s) effectively written. 0 if the writing of byte(s) appeared correct, 3 if you asked to send no byte (!), 4 if a time-out occurred in writing. 5 if the port is unknown. FUNCTION ReadCarSerie(VAR c: CHAR): BYTE; Call: "CommPort" designates the concerned port (0 to 7), Return: "c" = byte received, 0 if the reading of the byte appeared possible, 3 if no byte is available or if the port is closed, 5 if the port is unknown. FUNCTION WriteCarSerie(c: CHAR): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "c"= byte to send. Return: 0 if the writing of the byte appeared possible, 3 if this byte couldn't be written (full buffer or port closed), 5 if the port is unknown. 36 FUNCTION Peek_rcp(VAR c: CHAR): BYTE; Call: "CommPort" designates the concerned port (0 to 7), Return: "c" = read byte, 0 if the reading of the byte appeared possible, 3 if no byte is available or if the port is closed, 5 if the port is unknown. FUNCTION Poke_rcp(c: CHAR): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "c"= byte to insert in the buffer of receipt. Return: 0 if the writing of the byte appeared possible, 3 if this byte couldn't be written (full buffer or port closed), 5 if the port is unknown. FUNCTION WriteCmde(VAR Cmde: CHAR;number: BYTE;UseDTR: BOOLEAN): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "Cmde"= first byte of the control to send, "number"= Nb. of byte(s) making this command. "UseDTR"= Set DTR in order to frame the orders addressed to the device ? Return: 0 if the writing of byte(s) appeared correct, 2 if no byte was provided to be sent ! 5 if the port is unknown. PROCEDURE Status_Trait_Erreurs(VAR mode: BYTE;VAR codeEr,codeBk: CHAR); Call: "CommPort" designates the concerned port (0 to 7). Return: "mode" = substitution mode used. {"NonActif", "Replaces", "RempNULL", "NoBreakBuff", "BreakOnBuff"} "codeEr"= byte of replacement for the deficient bytes to currently use. "codeBk"= byte of replacement for the Break into buffer FUNCTION Def_Trait_Erreurs(mode: BYTE; code: CHAR): BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7), "mode"= substitution mode to activate. {"NonActif", "Replaces", "RempNULL", "NoBreakBuff", "BreakOnBuff"} "code"= byte of replacement for the deficient bytes. Return: Return FALSE if the "mode" is acknowledged by the driver, TRUE ("there is an error !") otherwise. PROCEDURE Etat_du_Modem(VAR Voie_active: CHAR; VAR Pret, Clear_to_send, Sonnerie, Porteuse, Changes, dDSR, dCTS, dRI, dDCD: BOOLEAN); Call: "CommPort" designates the concerned port (0 to 7). Return: "Voie_active": '1' for the COM1:, '2' for the COM2:, '3' for the COM3:, '4' for the COM4:, etc... Other variable: TRUE value (code 1) or FALSE (code 0) ("Pret", "Clear_to_send", "Sonnerie", "Porteuse", "Changes", "dDSR", "dCTS", "dRI", "dDCD"). PROCEDURE set_DTR; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE clear_DTR; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> 37 PROCEDURE set_RTS; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE clear_RTS; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE set_OUT1; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE clear_OUT1; Call: "CommPort" designates the concerned port (0 to 7). Return: <Nothing> PROCEDURE Send_break(length: BYTE); Call: "CommPort" designates the concerned port (0 to 7). "length" of the break interrupt signal between 0 and 250 eighteenth of a second. Return: <Nothing> FUNCTION Errors_Report(VAR Buff_overflow, Engorgement, Parite, Stop_bit, Break_it: BYTE): BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: "Buff_overflow", "Engorgement", "Parite", "Stop_bit", and "Break_it" are all up-dated. TRUE: at least one error took place since the last call to this function; FALSE if not... FUNCTION Port_Free: BOOLEAN; Call: "CommPort" designates the concerned port (0 to 7). Return: TRUE if we could reach the COM:, FALSE otherwise. FUNCTION HandShake_Status(Proto_type: BYTE; VAR SendEnabled: BOOLEAN): BYTE; Call: "CommPort" designates the concerned port (0 to 7), "Proto_type": RTS_CTS, DTR_DSR, RI, DCD or OUT1. Return: "SendEnabled"= TRUE if the transmit is authorized. 'Inactif': protocol or specified signal not used. Otherwise: the protocol or signal is used in the mode indicated in return ('Local,' 'Eloigne'(=remote) or 'Bilateral'). PROCEDURE HandShake_Setup(Proto_type: BYTE; VAR state: BYTE); Call: "CommPort" designates the concerned port (0 to 7), "Proto_type": RTS_CTS, DTR_DSR, RI, DCD, OUT1 or 'BothCmde' for RTS_CTS and DTR_DSR simultaneously. "state"={'Inactif,' 'Local,' 'Eloigne,' 'Bilateral'} Return: <Nothing> FUNCTION XonoffShaking_Status(VAR SendEnabled: BOOLEAN; VAR Nb_Xoff: BYTE): BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: "SendEnabled"=TRUE if the transmit is authorized. "Nb_Xoff": Number of Xoff received and no acknowledged. "Xon" and "Xoff" are up-dated to the value used by the driver for these codes. 'Inactif' (0): the Xon/Xoff protocol is not used. otherwise: Xon/Xoff is used in the returned mode in parameter ('Local', 'Eloigne', or 'Bilateral') 38 PROCEDURE XonoffShaking_setup(VAR state: BYTE); Call: "CommPort" designates the concerned port (0 to 7), "Xon" and "Xoff"= Defines the codes to use. "state"={'Inactif', 'Local', 'Eloigne', 'Bilateral'} Return: <Nothing> PROCEDURE Set_routine(VAR Uses: BOOLEAN; VAR Segment, Offsets: WORD); Call: "CommPort" designates the concerned port (0 to 7). Introduce the code of the routine to call in the "PROCEDURE Routine;" declared right before "Set_routine" in the COMINTRF.PAS file. This code must not provoke any call to the DOS. Return: Initialization done, the user routine will be called by the driver when it works (i.e. for all communication hard interrupt, transmit excluded). "Uses": TRUE or FALSE depending on whether a routine was already in place or not. "Segment":"Offsets"= pointer to this possible routine ! PROCEDURE Reset_routine(Segment, Offsets: WORD); Call: "CommPort" designates the concerned port (0 to 7). "Segment:Offsets": pointer to the routine to restore. Return: The routine for the hardware interrupt is reactivated. PROCEDURE Unset_routine; Call: "CommPort" designates the concerned port (0 to 7). Return: The user routine is disactivated ! PROCEDURE Set_err_routine(VAR Uses: BOOLEAN;VAR Segment,Offsets:WORD); Call: Introduce the code of the routine to call in the "PROCEDURE Err_Routine;" declared right before "Set_err_routine" in the COMINTRF.PAS file. This code must not provoke any call to the DOS, and it mustn't use any variable. Return: Initialization done, the user routine will be called by the driver in return of the interrupt 14h, if AH is not reported null. "Uses": TRUE or FALSE depending on whether a routine was already in place or not. "Segment":"Offsets"= pointer to this possible routine ! PROCEDURE Reset_err_routine(Segment, Offsets: WORD); Call: "Segment:Offsets": pointer to the routine to restore. Return: The designated routine for the int. 14h is reactivated. PROCEDURE Unset_err_routine; Call: <Nothing> Return: The errors management routine is disactivated ! PROCEDURE Locks; Call: <Nothing> Return: <Nothing> PROCEDURE Deverrouille; Call: <Nothing> Return: <Nothing> 39 FUNCTION GetPortName: BYTE; Call: <Nothing> Return: Return 13 if STARCOMM.EXE is not available as a DEVICE DRIVER; otherwise, up-dates the "NomDevice" variable. FUNCTION GetPortDevice: BYTE; Call: <Nothing> Return: Return 13 if STARCOMM.EXE is not available as a DEVICE DRIVER; Return 0 to 7 (for COM1: to COM8:) to designate the physical serial port in use. FUNCTION ResetPortDevice: BYTE; Call: "CommPort" designates the concerned port (0 to 7). Return: Return 0 if the commutation is made, 5 if the given port is marked unknown by the driver (the commutation is nonetheless achieved if the specified port is between the COM1: and the COM8:...), or 13 if STARCOMM is not available in DEVICE DRIVER mode. FUNCTION EmulBIOS: BOOLEAN; Call: <Nothing> Return: Return TRUE if the emulator is active, FALSE otherwise. PROCEDURE SetEmulBIOS(status: BOOLEAN); Call: "status"=TRUE to activate the BIOS emulator, FALSE to stop it. Return: <Nothing> FUNCTION OrdiType: BYTE; Call: <Nothing> Return: Return Type_PC, Type_XT, Type_AT, PS2_PC or PS2_AT. PROCEDURE SetOrdiType(status: BYTE); Call: "status"= Type_PC, Type_XT or Type_AT only. Return: <Nothing> 40 4- Description of the procedures interfacing to the C: ────────────────────────────────────────────────────── Prototype: byte <NAME> ([<ARGUMENT(S)>]) ---------- Call: - Global call variable - Call parameters Return: - global return variable - Return parameters - Functions return codes byte Check_STARCOMM_Present() Call: <Nothing> Return: "RS_accessible" to TRUE if a driver is present. 0= no driver, 1= STARCOMM loaded in BIOS mode, 2= STARCOMM is loaded as a DEVICE DRIVER. byte Version(char *NumVer) Call: <Nothing> Return: "*NumVer" contains the driver version in ASCII. UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte Open_Port() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the port could be opened. 5 if the port is unknown. 8 if the driver was already active. 9 if the port doesn't dispose of any buffers. byte OpenPort_Buff(word Segment, word Offsets, word Taille_in, word Taille_out) Call: idem preceding+ Seg:Ofs of the buffers and their sizes! Return: idem preceding except 9= "overflowed segment !" byte Close_Port(byte ProtegeBuff) Call: "CommPort" designates the concerned port (0 to 7). "ProtegeBuff" to TRUE if the transmit buffer must be emptiness before closing the port, to FALSE otherwise. Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the port could be closed. 5 if the port is unknown. 7 if it still remains some bytes to send (in this case, the port is still opened), if "ProtegeBuff" to TRUE. 10 if unable to recover the associate buffer. byte Port_Opened() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; TRUE if the port is opened, FALSE otherwise. byte Interdit_Port() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the port could be correctly closed, 10 if the "CommPort" port buffers pair is lost. The access of the port is forbidden in both cases. 41 byte Autorise_Port() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the access of the port could be authorized, 5 if the port doesn't designate any usable UART (the access to the port then remains forbidden). byte EtatVerrouilleComm(byte *Mode); Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the port could be accessed. 5 if the port is un-accessible. "*Mode" worth 2 to 5 upon the locking status in use (see next function for precise decoding of this...). byte VerrouilleComm(byte Mode); Call: "CommPort" designates the concerned port (0 to 7). "Mode" worth 2 to authorise any change, 3 to lock the speed, 4 to lock the format or 5 to lock both. Return: UN_CHECKED if presence of driver in RAM not checked; 0 if the port could be accessed, and the work is done. 5 if the port is un-accessible. byte SLOW_Ems() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, Return 5 if the port is unknown. byte FAST_Ems() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, Return 5 if the port is unknown. byte Send_SLOW() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, Return TRUE if the designated port transmits slowly, FALSE if it transmits in fast mode. void Get_Ports_Adresses() Call: <Nothing> Return: "BasePort1" to "BasePort4" are up-dated. byte Infos_Uart(byte *Uart_type, unsigned int *Uart_adresse, byte *Irq, byte *FIFO_actif, unsigned int *Taille_FIFO) Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; 0 or 5: the parameters are informed (5 if the port is considered as unknown). 42 byte Set_New_Uart(unsigned int Uart_adresse, byte Irq, byte FIFO_actif, byte Taille_FIFO) Call: "CommPort" designates the concerned port (0 to 7). "Uart_adresse" <- value of the new address, "Irq" <- value 2,3,4,5,7,10,11,12 or 15. "FIFO_actif"<- 0= NO, 1= YES "Taille_FIFO" <- from 2 to 15 bytes Return: UN_CHECKED if presence of driver in RAM not checked; Otherwise, Error code of the function: 0 modifications are achieved, 5 if the port is unknown, 11 if the port is open (the port must be closed to modify any of its physical parameters), 12 if the address reveals itself incorrect. byte Infos_Buffs(byte *Nb_utils, byte *Nb_maxi, unsigned int *Taille_InBuff, unsigned int *Taille_OutBuff) Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; the parameters are informed otherwise. byte Init_Port(unsigned char length, unsigned char stop_bit, unsigned char parity, long int speed, unsigned int *Taille_InBuff, unsigned int *Taille_OutBuff) Call: "CommPort" designates the concerned port (0 to 7), "length" = '5,' '6,' '7,' or '8' bits, "stop_bit" = '1' or '2,' "parity" = 'N','P','I','T' or 'R' for <N>o parity, even, odd, <T> mark, or <R> rest, "speed"={110,150,300,600,1200,2400,4800,9600,19200, 28800,38400,57600,115200} bits/second. Return: "*Taille_InBuff"= Size of the receipt buffer(s). "*Taille_OutBuff"= Size of the transmit buffer(s). (These 2 numbers must give the number of bytes). UN_CHECKED if presence of driver in RAM not checked, 1 if incorrect parameters (error= TRUE), 0 (FALSE) otherwise. byte Init_status() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; TRUE otherwise, with "Format" up-dated. byte Reset_Init_status(unsigned int Format) Call: "CommPort" designates the concerned port (0 to 7); "Format" specifies the reset value. Return: UN_CHECKED if presence of driver in RAM not checked, otherwise returns 1 for "incorrect parameter" or 0 if the initialization could be achieved. byte flush_buffers() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte flush_InBuff() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. 43 byte flush_OutBuff() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte ResetCOM_and_TimMAX(byte RdTim_MAX, byte *Old_RdTim_MAX, byte WrTim_MAX, byte *Old_WrTim_MAX) Call: "CommPort" designates the concerned port (0 to 7); "RdTim_MAX" and "WrTim_MAX" must be included between the ASCII values '0' and '9' in order to define a maximum treatment expectation (in reading or writing) included between ½ and 9 seconds. Passed the time limit thus defined, the procedure of reading (or writing) will abort on a "time-out" error. (The concerned procedures are "ReadSerie" and "WriteSerie"). Return: "Old_RdTim_MAX" and "Old_WrTim_MAX" returns the values used before the possible induced change by this call to the procedure. Note that a value of 0 placed in "RdTim_MAX" and/or "WrTim_MAX" to the call of the PROCEDURE will make that there won't be modification of the current values for the limits of time-out used by the driver. The returned variables "Old_RdTim_MAX" and "Old_WrTim_MAX" will be however correctly informed. UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte change_com_port(byte port) Call: "port"= N° of only port to keep opened (0 to 7 for COM1: to COM8:). "CommPort" is up-dated in return. Return: UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte Attend_Buff_ems_vide(byte Temps_maxi) Call: "CommPort" designates the concerned port (0 to 7), "Temps_maxi": 0 to 255 half seconds of expectation to the pleased. Return: UN_CHECKED if presence of driver in RAM not checked, 0 if the transmit buffer is emptiness, 4 if the maximum time limit of expectation is reached, 5 if the port is unknown. byte CheckBufferIn(unsigned int *Nb_a_lire) Call: "CommPort" designates the concerned port (0 to 7). Return: "*Nb_a_lire"= Nb. of byte(s) to read in receipt. FALSE: the BuffIn is emptiness; TRUE otherwise. UN_CHECKED presence of driver not checked. byte CheckBufferOut(unsigned int *Nb_libre) Call: "CommPort" designates the concerned port (0 to 7). Return: "*Nb_libre"= Nb. of free byte(s) in BuffOut. TRUE: BuffOut has room; FALSE otherwise. UN_CHECKED presence of driver not checked. 44 byte ReadSerie(unsigned char *car, unsigned int number, unsigned int *Nb_received) Call: "CommPort" designates the concerned port (0 to 7), "*car"= first byte in order to arrange the 'string' to receive, "number"= Nb. of byte(s) to read. Return: "*Nb_received"= Nb. of byte(s) really read. UN_CHECKED if presence of driver in RAM not checked, 0 if the reading of byte(s) appeared correct, 2 if the receipt is incorrect ("time-out"). byte WriteSerie(unsigned char *car, unsigned int number, unsigned int *Nb_written) Call: "CommPort" designates the concerned port (0 to 7), "*car"= first byte of the 'string' to send, "number"= Nb. of byte(s) making the 'string' Return: "*Nb_written"= Nb. of byte(s) effectively written. UN_CHECKED if presence of driver in RAM not checked, 0 if the writing of byte(s) appeared correct, 3 if you asked to send no byte (!), 4 if a time-out occurred in writing. 5 if the port is unknown. byte ReadCarSerie(char *c) Call: "CommPort" designates the concerned port (0 to 7), Return: "*c"= byte received, UN_CHECKED if presence of driver in RAM not checked, 0 if the reading of the byte appeared possible, 3 if no byte is available or if the port is closed, 5 if the port is unknown. byte WriteCarSerie(char c) Call: "CommPort" designates the concerned port (0 to 7), "c"= byte to send. Return: UN_CHECKED if presence of driver in RAM not checked, 0 if the writing of the byte appeared possible, 3 if this byte couldn't be written (buffer full or port closed), 5 if the port is unknown. byte Peek_rcp(char *c) Call: "CommPort" designates the concerned port (0 to 7), Return: "*c"= read byte, UN_CHECKED if presence of driver in RAM not checked, 0 if the reading of the byte appeared possible, 3 if no byte is available or if the port is closed, 5 if the port is unknown. byte Poke_rcp(byte c); Call: "CommPort" designates the concerned port (0 to 7), "c"= byte to insert in the receipt buffer. Return: UN_CHECKED if presence of driver in RAM not checked, 0 if the writing of the byte appeared possible, 3 if this byte couldn't be written (buffer full or port closed), 5 if the port is unknown. 45 byte WriteCmde(byte *Cmde, byte nombre, byte UseDTR) Call: "CommPort" designates the concerned port (0 to 7), "*Cmde"= First byte of the control string to send, "nombre"= Nb. of byte(s) making this command. "UseDTR"= Set DTR in order to frame the orders addressed to the device ? Return: UN_CHECKED if presence of driver in RAM not checked, 0 if correct writing, 2 if no byte was given to send ! 5 if the port is unknown. byte Status_Trait_Erreurs(byte *mode, byte *codeEr, byte *codeBk) Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, "mode"= substitution mode used. {"NonActif", "Replaces", "RempNULL", "NoBreakBuff", "BreakOnBuff"} "codeEr"= byte of replacement for the deficient bytes to currently use. "codeBk"= byte of replacement for the Break into buffer byte Def_Trait_Erreurs(byte mode, byte codes) Call: "CommPort" designates the concerned port (0 to 7), "mode"= substitution mode to activate. {"NonActif", "Replaces", "RempNULL", "NoBreakBuff", "BreakOnBuff"} "code"= byte of replacement for the deficient bytes. Return: UN_CHECKED if presence of driver in RAM not checked, return FALSE if the "mode" is acknowledged by the driver, TRUE ("there is an error !") otherwise. byte etat_du_modem() Call: "CommPort" designates the concerned port (0 to 7). Return: "Voie_active": '1' for the COM1:, '2' for the COM2:, '3' for the COM3:, '4' for the COM4:, etc... Other variable: TRUE value (code 1) or FALSE (code 0) ("Pret", "Clear_to_send", "Sonnerie", "Porteuse", "dDSR", "dCTS", "dRI", "dDCD"). TRUE: change(s) of modem status since the last call; FALSE otherwise; and UN_CHECKED if presence of driver not checked. byte set_DTR() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then DTR is switched to 1). byte clear_DTR() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then DTR is switched to 0). byte set_RTS() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then CTS is switched to 1). byte clear_RTS() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then CTS is switched to 0). 46 byte set_OUT1() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then OUT1 is switched to 1). byte clear_OUT1() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise (then OUT1 is switched to 0). byte Send_brake() Call: "CommPort" designates the concerned port (0 to 7), "length" of the break interrupt signal: between 0 and 250 eighteenth of a second. Return: UN_CHECKED if presence of driver in RAM not checked, TRUE otherwise. byte Errors_Report() Call: "CommPort" designates the concerned port (0 to 7). Return: "Buff_overflow", "Engorgement", "Parite", "Stop_bit", and "Break_it" are all up-dated. TRUE: at least one error took place since the last call to this function; FALSE: contrary case; and UN_CHECKED if presence of driver in RAM not checked. byte Port_free() Call: "CommPort" designates the concerned port (0 to 7). Return: TRUE if we could reach to the COM:, FALSE otherwise. UN_CHECKED if presence of driver in RAM not checked. byte HandShake_Status(byte Proto_type, byte *SendEnabled) Call: "CommPort" designates the concerned port (0 to 7), "Proto_type": RTS_CTS, DTR_DSR, RI, DCD or OUT1. Return: "SendEnabled" returns TRUE if CTS or DSR=TRUE. UN_CHECKED: presence in RAM of driver not checked. If the protocol or signal is used, its mode is returned: 'Local', 'Eloigne', or 'Bilateral'. Otherwise 0 is returned ('Inactif'). byte HandShake_Setup(byte Proto_type, byte state) Call: "CommPort" designates the concerned port (0 to 7), "Proto_type": RTS_CTS, DTR_DSR, RI, DCD, OUT1 or 'BothCmde' for RTS_CTS and DTR_DSR simultaneously. "state" = mode to activate, 'Inactif' (= 0 or FALSE !) in order to disactivate the harware hand-shaking (mode: {'Local,' 'Eloigne,' 'Bilateral'}) Return: UN_CHECKED if presence of driver in RAM not checked, TRUE in the other case. byte XonoffShaking_Status(byte *SendEnabled, byte *Nb_Xoff) Call: "CommPort" designates the concerned port (0 to 7). Return: "SendEnabled" returns TRUE if CTS=TRUE. "Nb_Xoff":Number of Xoff received and not acknowledged. "Xon" and "Xoff" are up-dated to the value used by the driver for these codes. UN_CHECKED if presence of driver in RAM not checked, otherwise: if Xon/Xoff is used, the utilization mode is returned ('Local,' 'Eloigne,' 'Bilateral'); if it is not used: 'Inactif' (= 0 or FALSE!) is returned. 47 byte XonoffShaking_Setup(byte state) Call: "CommPort" designates the concerned port (0 to 7), "Xon" and "Xoff"= Defines the codes to use. "state"={'Inactif', 'Local', 'Eloigne', 'Bilateral'} Return: UN_CHECKED if presence of driver in RAM not checked, TRUE: initialization done. byte Set_routine(unsigned Segprog int, unsigned Ofsprog int, unsigned int *OldSeg, unsigned int *OldOfs) Call: "CommPort" designates the concerned port (0 to 7), "Segprog"= Segment of the "FAR" user routine, "Ofsprog"= Offsets of this user routine. Return: UN_CHECKED if presence of driver in RAM not checked, TRUE or FALSE whether an old routine was already activated or not before the new one. "* OldSeg"= Segment of the old routine, "* OldOfs"= Offsets of the old routine. byte Unset_routine() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked, TRUE: disactivated routine. byte Set_err_routine(unsigned Segprog int, unsigned Ofsprog int unsigned int *OldSeg, unsigned int *OldOfs) Call: "Segprog"= Segment of the "FAR" user routine, "Ofsprog"= Offsets of this user routine. The code of the routine must not provoke any call to the DOS, and it must not use any variable ! Return: UN_CHECKED if presence of driver in RAM not checked, TRUE or FALSE depending on the existance of a routine already there before ! "*OldSeg"= Segment of the old routine, "*OldOfs"= Offsets of the old routine. byte Unset_err_routine() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked, TRUE: Routine is disactivated. byte Locks() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked, TRUE: Driver locking is done. byte Deverrouille() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked, TRUE: Driver unlocking is done. byte GetPortName() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked; Returns 13 if STARCOMM.EXE is not available as a DEVICE DRIVER. Otherwise, up-dates "NomDevice". byte GetPortDevice() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked; Returns 13 if STARCOMM.EXE is not available as a DEVICE DRIVER; otherwise, returns 0 to 7 for COM1: to COM8: 48 byte ResetPortDevice() Call: "CommPort" designates the concerned port (0 to 7). Return: UN_CHECKED if presence of driver in RAM not checked; otherwise, returns 0 if the commutation is made, 5 if the given port is marked unknown by the driver (the commutation is nonetheless achieved if the specified port is between the COM1: and the COM8:...), or 13 if STARCOMM is not available in DEVICE DRV mode. byte EmulBIOS() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked; Returns TRUE if the emulator is active,FALSE otherwise. byte SetEmulBIOS(byte status) Call: "status"=TRUE to activate the emulator,FALSE to stop it Return: <Nothing> byte OrdiType() Call: <Nothing> Return: UN_CHECKED if presence of driver in RAM not checked; Returns Type_PC, Type_XT, Type_AT, PS2_PC or PS2_AT. byte SetOrdiType(byte status) Call: "status"= Type_PC, Type_XT or Type_AT only. Return: <Nothing> 49 5- STARCOMM.EXE errors codes: ───────────────────────────── If AH<>0 the Carry-Flag is set (CF=1), otherwise it is null (CF= 0). (All following errors codes are given in decimal...) 0--> No error. Requested work is done. 1--> Number of an under-function OR working mode is unknown ! No treatment has been done... 2--> The reading routine was interrupted upon reception of a break interrupt signal. 3--> No byte has been read or written, due to lack of room (in writing) or due to absence of any byte to read; OR the port designated by the control is closed, what forbade any transac- -tion with it ! 4--> Time-out error in reading (the receipt buffer remains empty before the routine has read the Nb. of wanted bytes), or in wri- -ting (the transmit buffer remains full or is emptied too slowly). 5--> The serial port indicated is physically or logically unknown. 6--> Requested speed initialization is not valid. 7--> Transmit buffer not emptiness: thus, the port was not closed ! 8--> Serial port already active: Only one opening for each port ! 9--> Unable to open the port: no more available buffer is available OR (if opening the port with definition of external buffers) buffers no located in a same segment (or overflows of the data segment), OR one of the 2 specified buffers has a size less than 256 bytes (minimal admitted size for each buffer !). 10--> Unable to recover the buffer allocated to the port to close ! (This error normally couldn't ever occur...). This would have for consequence to lose one buffers pair !... 11--> Port is open: Any change of hardware parameters is FORBIDDEN ! 12--> New address specified for the port not adapted. 13--> STARCOMM.EXE is not available in its DEVICE DRIVER mode ! Notice that NO error is specified to a program asking for a new port initialization to use, port whose speed and/or format is/are locked: this permits to make the calling program think that its requesting is well achieved in order to make it work perfectly, even thought it can't modify part (or all) the serial port(s) inits ! 50 II- INTERFACING, for the PROGRAMMERS, from the DOS INT 21h: ═══════════════════════════════════════════════════════════ This software interface to the STARCOMM driver is not accessible except when STARCOMM.EXE is loaded in memory as a DEVICE DRIVER. It is necessary to note that the functions here-by added (see their descriptions below) add themselves to the basics functions of the interrupt 14H, interrupt that will still be available in this case... 1- direct Access to the driver: ─────────────────────────────── Function 3Dh: Open the access to the logical file "COMM:" that brings STARCOMM.EXE when loaded as a DEVICE DRIVER. The physical serial port associated to the "COMM:" unit is opened after this function. Call: AH = 3Dh AL = <Code of type of aperture> 0: open in reading, 1: open in writing, 2: open in reading + writing. DS:DX = Pointer to the DEVICE NAME, i.e. to "COMM" that is the logical name of STARCOMM.EXE. This string must be of ASCII-Z type, that is to say it must finishes with the hexa. code 0... Return: AX = HANDLER to access the device (if no error). AL = <Error code> otherwise (+CFlag set). Function 3Eh: Close the access to the device driver and provokes the transmit of an EOF code (=1Ah) if at least one byte was already sent to the means of the serial device driver. Remark: It is the transmission of this EOF code to the closing of the driver that allows to use "COMM:" as a full device from within the DOS prompt... ATTENTION: This function doesn't close the physical port associated to "COMM:" because it is possible that the transmit buffer is not entirely transmitted right as it is called ! Call: AH = 3Eh BX = HANDLER Return: AX = HANDLER to access the device (if no error). AL = <Error code> otherwise (+CFlag set). 51 Function 3Fh: Read data from the receipt buffer. If you ask to read more data than available in the buffer, this function waits for other data to be received before returning to the calling process. (Loop reading until completion of the request, or receipt of a break interrupt, or occurrence of a time-out error...). Note that on receipt of an EOF code, this DOS services routine considers that the calling application must react to this code. Until there has been closing then opening of the access to the device driver (functions 3Dh and 3Eh), the function 3Fh considers that the application didn't react to the EOF. From then on, it will only transmit this EOF code and won't return any other byte from the receipt buffer ! To this topic, read the second remark (referred as "ATTENTION:") in the following lines. Call: AH = 3Fh BX = HANDLER CX = Number of expected bytes. DS:DX = Seg:Off of first byte of the string in which to store the expected bytes. !! ATTENTION: Assure to reserve a sufficient !! space for the incoming bytes. !! ATTENTION: The DOS interprets all ^Z code !! (hexa. code 1Ah) as an EOF specifier. It !! won't be possible to read any more data !! received from the driver after reception of !! such a code. 3 solutions: !! 1°/ Use ASCII transcription (Cf CODAGES.DOC) !! in order to transmit some binary files. !! 2°/ After any ^Z reception, call the !! functions 3Eh (Close) and 3Dh (Open) to !! reset the process (Cf. TERMINAL.C example.). !! 3°/ Disactivate the DOS hand-shaking using !! its function 44h (IOCTL). !! Following the assembler code of it: !! - mov ah,44h ;Get Device data !! - mov al,0 !! - mov bx,<Dev_handle> !! - int 21h !! -... !! -<Treat the errors if CarryFlag_ON...> !! -... !! - mov ah,44h ;Set Device data OFF !! - mov al,1 !! - mov bx,<Dev_handle> !! - mov dx,0020h !! - int 21h !! Ctrl-P, Ctrl-S and Ctrl-Z will then be !! un-meaningful to the eyes of DOS. Return: CFlag to 1: AX = 0Bh. "Error in reading". CFlag to 0: AX = Number of bytes truly received. 52 Function 40h: Write data to send in the transmit buffer. If you try to write more data than the room remaining in the transmit buffer, this function waits to be able to finish its action before returning to the calling process. (Writing loop until completion or time-out). Call: AH = 40h BX = HANDLER CX = Number of bytes to send. DS:DX = Seg:Off of first byte of the string of bytes to send. Return: CFlag to 1: AX = 0AH. "Error in writing". CFlag to 0: AX = Number of bytes effectively written. Function 44h: Is the receipt buffer empty ? Call: AH = 44h AL = 06h (code of under-function) BX = HANDLER Return: AL = 0 for No, 1 for YES Function 44h: Is the transmit buffer full ? Call: AH = 44h AL = 07h (code of under-function) BX = HANDLER Return: AL = 0 for No, 1 for YES Function 44h: IOCTL-READ Demand to the "COMM:" file which port it is interfacing, the communication format in use, and the hand-shaking mode(s) used for this port (if any). Call: AH = 44h AL = 02h (Code of reading under-function) BX = HANDLER DS:DX = Pointer to the 11 consecutives bytes in RAM, reserved in order to receive the requested informations. !! ATTENTION: Reserve a sufficient space !! to receive the 11 bytes ! CX = Number of bytes making the string pointed by DS:DX (11 inevitably !). 53 Return: AX = DOS error code if CFlag is active. In case of no error, the 11 bytes pointed by DS:DX to the call has the following meaning: byte 1: Serial port interfaced by "COMM:": 0 (COM1:) to 7 (for the COM8:). byte 2,3: Speed, Format of communication. byte 4,5: Activity of RTS/CTS, DTR/DSR. byte 6 to 8: Activity of RI, DCD and OUT1. byte 9: Activity of Xon/Xoff. byte 10: Code used for Xon. byte 11: Code used for Xoff. In order to interpret the composition of the bytes 2 and 3, report the function 9 of the interrupt 14h (BH register for the speed, and BL for the format...). Function 44h: IOCTL-WRITE Indicates the driver the serial port that it interfaces, the communication format to use, and the hand- shaking mode to activate (if any). The modifications of format and hand-shaking are only acknowledged if the specified port is the one in use by the "COMM:" device driver; otherwise,there is only modification of the serial port number used by "COMM":, without NO other initialization (this permits to establish a multi-communication flow by using the "COMM:" file !...). Call: AH = 44h AL = 03h (Code of writing under-function) BX = HANDLER DS:DX = Pointer to the 11 consecutives bytes in RAM, reserved in order to transmit the news initializations to be used. The informations to store in these 11 bytes are identical to those developed in the 'Return' paragraph of the previous function. CX = Number of bytes making the string pointed by DS:DX (8 inevitably !). Return: AX = Code of DOS error if CFlag is active. 54 2- Procedures of interfacing for TURBO-PASCAL and TURBO-C: ────────────────────────────────────────────────────────── The supplementary previous functions (own to STARCOMM.EXE used as a DEVICE DRIVER) are also interfaced for the PASCAL and the C. This paragraph gives the variables and supplementary specifics functions, that also are in the STARINTF.PAS files and STARINTF.C. ────────────────────- Global variables: ───────────────────── NomDevice: Identification string of the device driver. It is the logical name associated to STARCOMM when it is installed in memory as a DEVICE DRIVER. This name is: "COMM:". handler_voie_serie: Key to access the DEVICE DRIVER. It is created at the opening of the DEVICE, and destroyed at its closing. COMM_ouvert: Status flag of the serial port activity (i.e. open or close). It is a boolean variable ! ─────────────────────────────────── Available procedures/functions: ──────────────────────────────────- Open_COMM: Provokes the opening of the logical file "COMM":. The handler to access the device is needed at the calling time to this function. Close_COMM: Provokes the closing of the logical file opened by Open_COMM. IOStream_READ: Permits to request to the installed driver the communication format (speed and structure) it is using, and its used hand-shaking... Contrarily to the similar available functions available from the BIOS 14h interrupt, this function uses the DOS IOCTL channel in order to inform you on the requested comm. specifications in use for the serial port represented by the logical port called "COMM:"... IOStream_WRITE: This is the complementary of the previous function: "IOStrteam_WRITE" permits to order the driver to use the new specified values (format and hand-shaking) OR to make the "COMM:" logical port to access a new physical serial port: - if the indicated serial port is different from the one in use, "COMM:" will represent this new port, and NO initialization nor hand- shaking working mode change is made; - otherwise the specified initializations are achieved. CheckCOMMIn: Is there any byte to read from the receipt buffer ? CheckCOMMOut: Is there any room in the transmit buffer ? ReadCOMM: Read N byte(s) from the receipt buffer. WriteCOMM: Send N byte(s) to the serial port via the transmit buffer. 55 3- Description of the procedures interfacing to the PASCAL: ──────────────────────────────────────────────────────────- Prototype: PROCEDURE|FUNCTION <name>[(<ARGUMENT(S)>)][:<type>]; ---------- Call: - Global call variables - Call parameters Return: - Global return variables - Return parameters - Functions return codes FUNCTION Open_COMM: WORD; Call: "NomDevice" contains the name of the DOS device driver. Initialized to "COMM" by default. Don't have to be modified ! Return: "port_ouvert" indicates the logical port status, i.e. if it is open (TRUE) or close (FALSE). 0 in case of an opening success. <DosCodeErr> for the other possible DOS errors. FUNCTION Close_COMM: INTEGER; Call: "NomDevice" contains the name of the DOS device driver. Initialized to "COMM" by default. Don't have to be modified ! Return: "port_ouvert" indicates the logical port status, i.e. if it is open (TRUE) or close (FALSE). -1 if the driver presence in RAM had not been checked before the call (by a "Open_COMM" call !). 0 in case of a closing success. <DosCodeErr> for the other possible DOS errors. FUNCTION IOStream_READ(VAR Voie_active: CHAR; VAR Format: WORD; VAR RTS_type, DTR_type, RI_type, DCD_type, OUT1_type, Xonoff_type: CHAR): BOOLEAN; Call: <Nothing> Return: TRUE in case of an error, FALSE otherwise. In the absence of errors, the global variable "Xon" and "Xoff" are informed. The parameters provided in arguments are up-dated: "Voie_active" --> '1' to '8' for COM1: to COM8:, "Format" --> high byte = speed, low byte = structure. (See the interrupt 14h, function 9 for the values/ meaning correspondences...). "RTS_type" --> 0, 'B,' 'E' or 'L' in order to define the active mode (Local, Distant, or Bilateral...). 56 FUNCTION IOStream_WRITE(VAR Voie_active: CHAR; VAR Format: WORD; VAR RTS_type, DTR_type, RI_type, DCD_type, OUT1_type, Xonoff_type: CHAR): BOOLEAN; Call: The global variables "Xon" and "Xoff" must be informed. The arguments parameters are to be fill as indicated below: "Voie_active" --> '1' to '8' for COM1: to COM8:, "Format" --> high byte = speed, low byte = structure. (See the interrupt 14h, function 9 for the values/ meaning correspondances...). "RTS_type" --> 0, 'B,' 'E' or 'L' in order to define the active mode (Local, Distant, or Bilateral...). Return: TRUE in case of error, FALSE otherwise. FUNCTION CheckCOMMIn: BOOLEAN; Call: <Nothing> Return: FALSE: the input buffer is emptiness or the port is closed, TRUE otherwise. FUNCTION CheckCOMMOut: BOOLEAN; Call: <Nothing> Return: TRUE if the output buffer has room; FALSE otherwise. FUNCTION ReadCOMM(VAR c: CHAR; nombre: WORD): INTEGER; Call: "c"= First byte in order to store the 'string' to receive, "nombre"= Nb. of byte(s) to read. Return: 0 if the reading of byte(s) appeared correct <DosCodeErr> if incorrect receipt (Time-out...) -1 if no byte could be read. FUNCTION WriteCOMM(VAR c: CHAR; nombre: WORD): INTEGER; Call: "c"= First byte of the 'string' to send, "nombre"= Nb. of byte(s) making the 'string'. Return: 0 if the writing of byte(s) appeared correct, <DosCodeErr> if incorrect receipt (Time-out...) - 1 if no byte could be written. 57 4- Description of the procedures interfacing to the C: ────────────────────────────────────────────────────── Prototype: byte <NAME> ([<ARGUMENT(S)>]) ---------- Call: - Global call variables - Call parameters Return: - Global return variables - Return parameters - Functions return code int Open_COMM() Call: "NomDevice" contains the name of the DOS device driver. Initialized to "COMM" by default. Don't have to be modified ! Return: "port_ouvert"=TRUE if successful opening. 0 in case of opening success. 8 if the driver was already active. <DosCodeErr> for the other DOS possible errors. int Close_COMM() Call: "NomDevice" contains the name of the DOS device driver. Initialized to "COMM" by default. Don't have to be modified ! Return: "port_ouvert"=FALSE if successful closing. UN_OPENED if presence of driver in RAM not true. 0 in case of closing success. 7 indicates that it still remains bytes to send out: the port hadn't been close ! <DosCodeErr> for the other DOS possible errors. byte IOStream_READ(byte *RTS_type, byte *DTR_type, byte *RI_type, byte *DCD_type, byte *OUT1_type, byte *Xonoff_type) Call: <Nothing> Return: UN_OPENED if presence of driver in RAM not true, 1 (TRUE) if any error, 0 (FALSE) otherwise. In the absence of any error, the globals variables "Xon" and "Xoff", "Voie_active" and "Format" are informed. The arguments "*RTS_type", etc. are up-dated. "Voie_active" --> '1' to '8' for COM1: to COM8:, "Format" --> high byte = speed, low byte = structure. (See the interrupt 14h, function 9 for the values/ meaning correspondances...). "RTS_type" --> 0, 'B,' 'E' or 'L' in order to define the active mode (Local, Distant, or Bilateral...). 58 byte IOStream_WRITE(RTS_type byte, DTR_type byte, RI_type byte, DCD_type byte, byte OUT1_type, Xonoff_type byte) Call: The globals variables "Xon" and "Xoff", "Voie_active" and "Format" must be informed, in addition to the function explicit arguments. "Voie_active" --> '1' to '8' for COM1: to COM8:, "Format" --> high byte = speed, low byte = structure. (See the interrupt 14h, function 9 for the values/ meaning correspondances...). "RTS_type" --> 0, 'B,' 'E' or 'L' in order to define the active mode (Local, Distant, or Bilateral...). Return: UN_OPENED if presence of driver in RAM no true, 1 (TRUE) if a error is brought back, 0 (FALSE) otherwise. byte CheckCOMMIn() Call: <Nothing> Return: FALSE: the input buffer is emptiness; TRUE otherwise. UN_OPENED: port not opened. byte CheckCOMMOut() Call: <Nothing> Return: TRUE: the output buffer has room; FALSE otherwise. UN_OPENED: port not opened. int ReadCOMM(byte *car, unsigned int number) Call: "*car" = first byte in order to store the 'string' to receive, "number"= Nb. of byte(s) to read. Return: UN_OPENED: the port was not opened before, 0 if correct reading, <DosCodeErr> if an error is produced, -1 if no byte could be read. int WriteCOMM(byte *car, unsigned int number) Call: "*car"= first byte of the 'string' to send, "number"= Nb. of byte(s) making the 'string'. Return: UN_OPENED: the port was not opened before, 0 if correct writing, <DosCodeErr> if an error is produced, -1 if no byte could be written. 59 5- DOS errors codes: ──────────────────── From the interrupt 21h, the errors codes returned are the usual codes returned from the DOS. Here are the mains DOS errors codes in connection with the accesses to the "character" device drivers type: 0--> No error. The requested work is achieved. 1--> Function number is unknown ! 2--> Unknown file (verify that the DEVICE name is still "COMM:"...). 4--> Too many open files. 5--> Access denied (protection in reading or writing). 6--> HANDLER not valid. 8--> Memory not sufficient in order to create a new "handler". 29--> Error in writing. 30--> Error in reading. 31--> Internal error to the system. 60 III- INTERFACING, for the PROGRAMMERS, to SCLIB.OBJ: ════════════════════════════════════════════════════ The BIOS mode of STARCOMM.EXE may be integrated to any application made in a language that generates files to the ".OBJ" format before its link phase. It is sufficient, when such is the case, to bind the application "*.OBJ" file(s) with SCLIB.OBJ (from SERIAL PORTS MANAGER). This library will then permit to install the usual interfacing of STARCOMM.EXE on the interrupt 14h, to uninstall it, and will even permit to call the classics services from this interrupt without having to generate any classical "INT 14h" call ! The 3 globals following functions (THAT DO NOT USE ANY STACKED PARAMETER AT THEIR CALL) permits this operation; Note that the first 2 don't assure the preservation of the CPU registers to the return: Set_SCL --> Installs and activates the driver integrated to SCLIB. Use the initialization addresses, IRQ, and parameters defined by default in the library (use the functions 09h, 0Ah and 2Eh in order to adapt the hardware parameters...). There will always be 2 buffers of ½ Ko created for each logical port recognized (8 in all) without any possibility to make any other choice concerning the internals buffers sizes (Cf. function 07h with AL=6 in order to use your own buffers,so called "external" relatively to the library !) Call: <Nothing> Return: CARRY SET if "Set_SCL" was already called at least once before the present call: NO ACTION has THERE- FORE BEEN MADE ! No risk of embedded installations in case of thoughtlessly repeated calls. UnSetSCL --> Disactivates the driver integrated to SCLIB. The opened ports are closed and the used interrupts are freed. The used UART is initialized as found at the time of the first call to "Set_SCL". Call: <Nothing> Return: CARRY SET if "Set_SCL" was not called at least once before "UnSetSCL" ! No risk of destructive uninstallations in case of multiple calls. SCLservs --> Permits the direct call to the services functions, without generating the software interrupt 14h. This could be interesting for the programs working under some "MULTI-TASKER" that do not share the INT 14h without modifying some CPU registers to the transition !!! Call: Load the registers as needed in order to call the requested function, like you would for an interrupt 14 call (report to the paragraph I of the present document). Return: CARRY SET to the return if the driver was not activated yet, using "Set_SCL"; otherwise the registers are returned as indicated in the paragraph I of STAR_REF.DOC. Of course, it is also possible to issue an "INT 14h" instead of a "call SCLservs" ! The 3 "last" functions of the interrupt 14h incorporated to SCLIB.OBJ are disactivated because they only concern the DEVICE mode of STARCOMM. So, 2Ah and 2Ch will always return an error code 1 (i.e. "under-function unknown" !) and 2Bh will always return a code 13 (i.e. "driver not loaded as a DEVICE DRIVER !"). The simple application named DEMO_LIB.ASM shows how to achieve this exploitation of SCLIB.OBJ. 61 ANNEX: Management of the differents hand-shakings ╔═══════════════════════════════════════════════════════════════╗ ║ ATTENTION ---> At all events, the OUT2 signal of the used ║ ║ controller must be set to TRUE. In the contrary case, the UART║ ║ has no more the material possibility of giving out its IRQ to ║ ║ the processor (via the 8259 interrupt controller of course !).║ ║ THEREFORE: DO NOT MODIFY THE OUT2 SIGNAL IN ANY CASE ! ! ! ║ ╚═══════════════════════════════════════════════════════════════╝ 1- Managements integrated the serial driver: ──────────────────────────────────────────── The SERIAL PORTS MANAGER's STARCOMM.EXE driver knows the management of Xon/Xoff (software hand-shaking), RTS/CTS and DTR/DSR (hardware hand-shaking). These 3 pairs of flow management signals (which can be set by using the options /BX, /BC and /BD, or by the call to the appropriates services), are managed as follows: ■ Xon/Xoff: When the receipt buffer doesn't contain more than a 100 bytes free (or less...), all received byte provokes the transmit of an Xoff code (= 13h). As soon as more than 2/3 of the receipt buffer are all over free again, there is transmit of an Xon code (= 11h) to every reading from the consumer in this receipt buffer; this to competition of 10 Xon consecutively sent (i.e. sent without any Xoff being sent back between them because the receipt buffer was found "full" again !). An Xon is also sent each time the receipt buffer is emptied due to an order from a local user program. For security (case of a communication error occurring on the Xon code !...), STARCOMM.EXE considers it receives an Xon code following each "error in receipt" interrupt generated by the UART. REM: ACK/ETX (or all other pair !) can in fact be managed under covering of Xon/Xoff using the possibility offered to specify the hexa. values of Xon and Xoff ! ■ RTS/CTS: The management logic of this pair is identical to the one of Xon/Xoff. Merely, "Send of an Xon (/resp. Xoff)" becomes "RTS is set to TRUE (/resp. to FALSE)"; and "the transmit doesn't take place that if Xon is the last code received among the Xon and Xoff codes" becomes "the transmit doesn't take place that if the CTS signal is set to TRUE" ! REM: Whether this protocol is used or not, the RTS local signal is always initialized to TRUE at the same time as the concerned port is opened, and it is set to FALSE when the port is closed (whether it is explicitly concerning a port opening or a port closing, or only the change of the only used port !). 62 ■ DTR/DSR: Used as flow management signals, they are managed like the RTS/CTS pair (see above...). ATTENTION: DTR is also exploited by the device command transmit function, by the functions of opening and closing of a physical port (DTR is activated to the opening and disactivated to the closing), by the "change serial port in use" function, and by the treatment of the communication errors installed under the hardware interrupt of the associate UART to the serial port exploited. Therefore: once the port to exploit is open, do initialize DTR/DSR, and avoid using the transmit commands function in its "control via DTR" mode. But note this function is not a 100% incompatible with the DTR/DSR hand-shaking since it sets off the DTR to send its specified command, then it re-establishes DTR once the command send is achieved (without nevertheless verifying that the receipt buffer has any more room...). It is important to note that these hand-shaking can also be actived in one-sided mode (ascending or descendant) to the means of the following command-lines: "/LC", "/EC", "/LD", "/ED", "/LX", and "/EX"... ■ RI, DCD and OUT1: These signals can also be managed by STARCOMM. RI and DCD (input signals) are managed like CTS and/or DSR, whereas OUT1 (output signal) is managed like RTS and/or DTR. Finally, notes that the hardware hand-shakings (RTS/CTS, DTR/DSR, RI...) have full priority on the software hand-shaking: if, as an example, RTS/CTS is used and that CTS=FALSE, it becomes impossible for Xon/Xoff to send any control code, even though this software protocol is effectively active ! In order to establish a hardware hand-shaking (with STARCOMM) that is fully personal to you only, report in 3 below. 2- PC-PC local link and hand-shaking: ────────────────────────────────────- ┌──────────┐ ┌──────────┐ │ 2├───── ┌───┤3 │ │ PC #1 3├──────┘───┤2 PC #2 │ │ 7├──────────┤7 │ └──────────┘..........└──────────┘ ?? hand-shaking control ?? Among the embedded protocols, only Xon/Xoff is usable to this whichever is the express nature of your null modem serial cable. If you dispose of a more complete null-modem cable (Cf. A), you could exploit one of the two RTS/CTS and DTR/DSR hardware hand-shaking, or even these 2 at the same time (even though, in theory, the utilite of it is very questionable !...). If you want to create your own hand-shaking using to RTS, CTS, DTR, DSR, RI, DCD, and/or OUT1 signals, report in paragraph 3 below... 63 3- Personal exploitation of a hardware hand-shaking: ───────────────────────────────────────────────────- As explained in the paragraph 1- above, STARCOMM knows how to use the output signals RTS, DTR and OUT1 as well as the input signals CTS, DSR, RI and DCD in order to establish a hardware hand-shaking. The hand- shakings based on the RTS/CTS and DTR/DSR pairs, very classicals, are easy to implement using the driver functions calls 21h and 22h. However, it remains possible to define any signals pairs combining based on these 7 different controls signals in order to implement a hardware hand-shaking adapted to your own needs (associated to your own developed application !). This need could result of the particular working of a device with which to converse, or of the will to develop a protecting for your own work thanks to a cable specially designed for your program. FOR EXAMPLE, supposes that your application must not function except with a special cable well stocked with the merchandised program. You decided the following diagram for your cable (that is an oriented cable, i.e. NOT symmetrical, for the interest of the example...): MASTER UNIT SLAVED UNIT TX ------> RX RX <----- TX Gnd ------- Gnd OUT1 ------> DSR DSR <----- OUT1 Couple OUT1/DSR assigned a hardware bilateral flow control. RTS ------> CTS Couple RTS/CTS one-sided (remote of the main station only !). On the MASTER UNIT, your application will activate (function 22h): - the utilization of OUT1 (it has the DISTANT status inevitably...), - the DTR/DSR protocol in LOCAL mode so that only DSR is used, - the RTS/CTS protocol in DISTANT mode so that only RTS is used. On the SLAVED UNIT, your application will activate, in addition of the 2 first signals indicated for the main station (symbolized by "..."): - ... - the RTS/CTS protocol in LOCAL mode so that only CTS is acknowledged. The signals OUT1, DSR and RTS-->CTS will then be dynamically used by the serial driver in order to inform the master and slave stations of the transmission possibilities resulting from the receive and transmit buffers states: The slave won't send any more data to the master but if DSR AND CTS are active, and the master won't communicate with the slave but if DSR is active (on its side). REMARK: It is also possible to use all or part of these signals, under STARCOMM, as if there were "STROBES", that is to say as identification signals statically set by the application. It is then sufficient to directly order the signals status as needed, and in taking carefulness of not using a same signal at the same time as a strobe AND as a flow manager ! (Recall: the function 20h, explained in page 19, permits to control the status of all these signals).